Optional local client and Docker host

The controller, web gateway and coding sessions run on the server. A laptop needs only Python 3 and SSH to use the launcher installed by the standalone installer:

devctrl tui remote
devctrl web remote

The first command displays the server-hosted TUI over SSH. The second starts the existing server web container if necessary, prints its private HTTPS link and opens the local browser. Use --no-open to print the link only. Browser uploads, downloads and session drag-and-drop work without a local helper.

The TUI uses a 256 MiB V8 old-space ceiling by default. For a larger inventory, use DEVCTL_TUI_HEAP_MB=512 devctrl tui remote (accepted range: 128–4096 MiB). This is an interface setting, separate from container RAM limits and existing coding sessions. Refresh an older standalone launcher with the installer's --launcher-only SSH_TARGET mode to receive this setting; it does not reinstall the server. TUI memory diagnostics (source access required).

An existing console can also serve a local TUI through devctrl connect, with optional owned Docker/device enrollment over HTTPS. Continuous WSS Exchange is a preview with a restart-verification limitation. Read URL connections and current capabilities before choosing that transport.

Synchronize selected local folders

For a fresh server, the main installer configures this same client automatically when its first argument is a local Git folder:

curl -fsSL https://devctrl.dev/install.sh | sh -s -- './my-project' 'remote-server'

It reads the folder's Git remote, sets up the server, and maps my-project/agent-interchange to the new Project. Local Docker and SSH-agent requirements are checked first. A URL argument sets up only the server and launcher, leaving the local client optional. Whole Git checkouts and uncommitted changes are not synchronized by Exchange. See folder-based installation.

For an existing server, configure or change the client separately:

Install Docker Desktop on macOS or Docker Engine on Linux, connect to each server once to verify its SSH host key, and load its key into an unlocked SSH agent. Then run:

devctrl client install

Choose one or more placed Projects and a separate local Exchange directory for each. These are bidirectional mirrors of the Project's agent-interchange, not full Git checkouts. Non-interactive configuration is explicit:

devctrl client install \
  --project example-app="$HOME/devctrl-exchange/example-app"

Use the Project ID displayed in the picker. Add a saved console name after install to use another server. If an execution host has a different SSH alias, add --host HOST_ID=SSH_ALIAS. Additional execution hosts currently use the rootful Docker profile; the console host also supports the installer's rootless profile.

The launcher pulls ghcr.io/devctrldev/devctrl-client-agent:1, a public AMD64/ARM64 image, and records its immutable digest for this installation. No repository checkout, local Node.js, local controller or local build is required. Repeat client install to change selected folders or update the image. It rotates only this client's credential and replaces only its own labeled container. Existing legacy devctl containers and running remote sessions are preserved.

The client connects outward over SSH to the existing server controller and execution hosts. It retries disconnected SSH/API transport automatically. Sleeping the laptop pauses folder sync; it does not stop server sessions. A revoked or invalid credential suspends synchronization. A controller that cannot confirm the selected Project scope is rejected; update the server before installing this client.

devctrl client status
devctrl client logs
devctrl client stop
devctrl client start
devctrl client remove

Status shows container state, last controller heartbeat time and selected folder mappings; an old heartbeat is not evidence of a live connection. Stop retains the container; remove retains local files, settings, credential and Unison state for reinstallation. Remove does not revoke the server credential. Reinstall after removal. Stop the optional local host module first if it uses this client's transport.

What the file client can access

Settings live below ${XDG_CONFIG_HOME:-$HOME/.config}/devctrl/clients/CONNECTION/, with private 0600 credential/config files. The only local executable is ~/.local/bin/devctrl. Runtime state lives in the same client directory. macOS currently uses Docker Desktop's SSH-agent socket; SSH jump/proxy commands and other macOS container engines are not supported by this bootstrap. Unlock/reload the agent after reboot if your operating system requires it.

Explicitly connect local Docker as compute

File synchronization does not make the laptop an execution host. To enable local workloads as well, install the file client transport first, then explicitly run:

devctrl host install local

This pulls the separate host variant ghcr.io/devctrldev/devctrl-client-agent:host-1 and starts a separate host-agent container. It shares the client's outgoing controller connection, but gets its own host enrollment credential and managed storage. Only this host module receives the local Docker Unix socket. This grants control over the selected local Docker daemon and is an explicit additional trust boundary. The installer accepts local Unix-socket contexts only, and refuses to replace an existing legacy devctl-local-host-agent-1.

The host appears in Hosts on the server console. Place a Project on it to create workloads; enrollment alone starts no coding session. Managed data lives under ~/.local/share/devctrl/hosts/CONNECTION/, mounted at the same absolute path inside the host agent so Docker bind paths resolve correctly. Container/runtime operations still enforce the host's reported capabilities; this command does not configure hard resource delegation or promise rootless network enforcement.

devctrl host status local
devctrl host stop local
devctrl host start local

Stopping this module leaves Project containers, sessions and files intact. Stop it before reconfiguring/removing the file client's shared transport, then start it again to join the current transport container. Existing server workloads never depend on this module. The local host is unavailable when the laptop sleeps; choose remote compute for unattended work.

Maintainer publication

.github/workflows/client-agent-image.yml publishes both AMD64 and ARM64 images from the same source. The lightweight client uses docker/client-agent.Dockerfile; the host variant reuses the existing root Dockerfile host-agent target. Host platforms build on separate native AMD64/ARM64 runners with independent caches; a manifest is published only after both succeed. Both tags share the public GHCR package. No account credentials are baked into the images. Registry publication and package visibility are separate: an organization administrator must allow Public package creation and set the package Public once. The installer does not need a GitHub registry login afterward.

Verification

Run python3 -B docker/standalone-client.test.py for isolated launcher tests and the client-agent/controller suites for transport and Project-scope checks. An opt-in Docker test builds an SSH fixture with disposable keys and a mock controller, then exercises the actual client image, two-way Unison, ignore policy, reconnect and credential revocation:

docker build -f docker/client-agent.Dockerfile -t devctrl-client-agent:test .
DEVCTRL_CLIENT_TEST_IMAGE=devctrl-client-agent:test python3 -B docker/standalone-client.integration.py

It uses no paid account, live Project or real server credential. Fixture containers, network, image and temporary keys are removed afterward.