Connect a computer through a console URL
devctrl connect
devctrl connect https://console.example/ --local-docker
devctrl connect https://console.example/ --local-client \
--exchange PROJECT_OR_WORKSPACE_ID=./repository/agent-interchange
The first command asks privately for a console link or origin, then runs a local
TUI against the remote controller through HTTPS. Use the private prompt or
--url-stdin for a link containing a key or invitation; do not put credentials in
shell history or process arguments. A viewing/control link for one session cannot
sign in to the whole console or enroll a computer.
On a multi-user server, use the origin and sign in with your personal user ID and password, or redeem a one-use invitation. The shared operator key is not accepted in user mode. Saved sign-in uses private files and rotating refresh tokens. Device, client and host ownership comes from that authenticated user, never an arbitrary owner ID supplied by the laptop.
Choose local capabilities
Plain connect needs the supported local Node runtime and Python launcher. It
does not install Docker, download agent images, or expose local folders.
--local-docker explicitly enrolls an execution host and a file/service client
for the selected local Docker daemon. --local-client enrolls only the latter.
These optional Docker clients currently require a local Unix-socket context on
macOS or Linux. No local controller or SSH connection to the server is needed.
The gateway checks the independent enrolled credentials for existing HTTP, binary-transfer and WebSocket routes. It does not insert operator credentials. Only an explicitly requested execution-host agent receives the Docker socket. Exchange workers never receive it.
Bind an Exchange folder
Repeat --exchange PROJECT_OR_WORKSPACE_ID=FOLDER for each dedicated local folder
you want to synchronize. The launcher resolves the exact owned remote target and
shows shared roots explicitly. If several projects use the same server Exchange
root, configure one common local folder for that root. It does not infer a
repository, home or parent-directory mount.
The chosen folder is a whole-folder read/write grant to the remote peer. Ordinary ignore patterns select synchronized files; they are not access controls. Do not select a directory containing unrelated private data. You may deliberately place an environment file, key or another input inside the chosen Exchange folder for your agent to read. Client transport credentials, checkpoints and other project roots remain outside this grant.
Both native Unison endpoints run in confined Docker workers. Each worker sees one Exchange mount, read-only runtime and its own temporary metadata; the local worker additionally sees only its binding's private IPC socket. They have no network access, Docker socket or transport credentials. Hardlinks are rejected across the whole selected folder, including ignored names; symlinks are not followed by ordinary synchronization.
--exchange-ignore PROJECT_OR_WORKSPACE_ID=PATH_TO_GITIGNORE optionally supplies
one external ignore file to the local supervisor. In-place edits are observed.
Replacing that file atomically changes the host inode and requires re-enrolling
that file bind. Nested ignore files inside Exchange follow ordinary updates.
Synchronization uses authenticated WSS with bounded, acknowledged frames. The
implementation retains the previous common native archive until both endpoints
finish. It preserves the existing Unison conflict policy (prefer=newer and
copyonconflict). Other users cannot select this device's roots or metadata.
Continuous HTTPS Exchange is a preview. The actual controller/gateway/native fixture verifies first synchronization, owner isolation and in-flight revocation. The clean restart/conflict fixture still has an intermittent failure after in-place host edits: an independent process in the selected worker can see old file size/mtime while the host sees the changed file. This was observed on macOS26.4.1 / Docker Engine29.8.2; a separate bounded bind diagnostic identified VirtioFS. The exact failing mount was the canonical selected folder. Ordinary live edits and several diagnostic runs pass, but neither explicit mount consistency nor worker recreation reliably resolved the failing regression. Those observations do not establish reliable restart behavior. Keep this limitation visible until the clean native regression passes; device enrollment alone is not evidence that files are current. The existing SSH folder client remains available. HTTPS TUI sign-in does not depend on Exchange being enabled.
Remote workers reserve existing user/host resource budget before execution. Each sequential scan/stream job uses 128 MiB RAM, 0.25 CPU, 32 PIDs and one concurrency slot, without additional swap. Existing hard allocations also require verified cgroup/filesystem placement. Missing, stale or exhausted capacity blocks synchronization; it never increases quotas or stops an active coding agent. A closed connection retains its charge until the host confirms worker termination. An uncertain Docker create response requires authoritative reconciliation before another generation can reuse that slot. Exact phase-absence proofs distinguish older inventory from a live worker; newer contradictory inventory blocks reuse.
Only the canonical operator without an explicit allocation can use observed-host admission. This mode checks fresh physical/default-parent headroom and pending commitments, with finite worker caps. Existing unbounded infrastructure still has unknown maxima; this mode makes no aggregate user-quota guarantee. Any configured operator allocation and all tenant allocations keep their stricter checks. Tenant transport also requires the host's managed egress-component accounting capability; older hosts are shown as unavailable rather than silently bypassing accounting.
Each owner has a bounded 64 MiB checkpoint budget, including atomic replacement peak; old checkpoints expire after 30 days. This is a metadata budget, not a hard aggregate disk-quota claim on filesystems without a supported quota backend. It never deletes Exchange files.
Verification and runtime limits
| Capability | Status | Evidence or limit |
|---|---|---|
| Local TUI sign-in and owned device enrollment | Implemented; local tests | Personal sign-in/refresh and device ownership retain their existing handlers. |
| First two-way WSS Exchange and revocation | Native fixture tested | Actual controller/gateway, native Unison and confined Docker workers; the test pool uses admission-only accounting. |
| Common-checkpoint restart and conflict recovery | Partially verified | The clean in-place restart regression remains unresolved. |
| Resource admission and egress lifecycle | Implemented; automated tests | Real SQLite/HTTP/heartbeat cases cover pending creation, revocation, stale inventory and exact termination. |
| Aggregate hard tenant quotas | Deployment-dependent | Requires existing verified cgroup/filesystem enforcement; a synthetic test pool does not prove it. |
| Rootless or user-namespace-remapped local Docker | Unsupported by this launcher | UID mapping is checked before local workers are started. |
Native fixtures currently use Linux ARM64, Node24.22.1 and Debian Unison2.52.1 (OCaml4.13.1). They require local Docker and OpenSSL, synthetic credentials only, and no paid account. Windows/Android application UI work is separate from this Unix-socket local-client transport. See the opt-in tests under e2e/https-exchange.
Manage the enrolled device
devctrl device status DEVICE_ID
devctrl device stop DEVICE_ID
devctrl device start DEVICE_ID
devctrl device remove DEVICE_ID
The launcher prints the generated device ID after enrollment. Configuration and
credentials live under its private devctrl/url-devices/<device-id> directory.
Stop pauses local transport; remove revokes enrolled credentials and removes only
that device's managed local tooling. Project data is retained.
The owned GET /v1/local-devices list omits credentials. The explicit
DELETE /v1/local-devices/:id operation revokes the device's client/host identities
without deleting project data. Disabling its server user also invalidates those
credentials. Enrollment returns secrets only once; inspect the device list before
retrying an uncertain request. These owner-authorized operations are discoverable
through the existing operator MCP catalog. Never paste enrollment responses into
an agent session.
Existing SSH/Unison client configuration remains available. HTTPS enrollment does not copy local CLI accounts or publish the rest of the computer's filesystem.