Install on an ordinary SSH account

Run the server controller and shared TUI/web application on a prepared Rootless Docker backend. Application users remain separate from SSH accounts, and each server user keeps private containers and storage, including when using a shared subscription. See shared accounts (source access required) and the capability overview.

Automatic limited tooling account

On a fresh Ubuntu server with systemd, the normal installer uses the operator's root/passwordless-sudo SSH connection for bootstrap. It creates a separate locked OS account (devctrl, or an unused devctrl-N if that name already belongs to someone), prepares its private Rootless Docker daemon and runs the controller, execution host, web gateway and native host-session runner under that account. No extra switch is required:

curl -fsSL https://devctrl.dev/install.sh | sh -s -- \
  'https://github.com/devctrldev/devctrl.git' 'root@remote-server'

The account has a private home, no interactive login/password, no sudo grant and no membership of rootful Docker or other privileged groups. Bootstrap allocates non-overlapping subordinate UID/GID ranges, enables the user systemd manager and lingering, and verifies the actual daemon's rootless namespace/socket. Required packages and the official Docker Rootless setup are prepared automatically. Ubuntu's user-namespace restrictions use a narrow RootlessKit AppArmor profile; host protections are not globally disabled. SSH root access remains available to the operator.

The saved launcher keeps using the original SSH connection. A root-owned helper drops to the tooling account before Docker/TUI/web commands, with an environment that excludes the operator's credentials and Docker contexts. This OS account is separate from Server Users, which still own their projects, containers, credentials and quotas independently.

This does not migrate existing rootful installations. Existing source/state, containers and occupied console ports are refused before account/package/service changes. Failed bootstrap can reuse its recorded account while no application installation exists; partial application data is retained for inspection. Active sessions and workspace ownership are never moved automatically. Older execution-host enrollment/upgrade retains its existing rootful behavior.

Automatic setup requires Rootless Docker 29.9.1+, verified against the same restricted-network allowlist and bypass tests as the rootful backend. Existing prepared rootless daemons below that version must be upgraded before restricted workspaces start; policy is never changed to unrestricted automatically. Aggregate per-user hard quotas still require the explicit delegation described below.

Use --rootful only to select the trusted compatibility profile, including non-systemd installer labs. Its Docker socket gives management tooling root-equivalent host authority. Adding a user to the Docker group provides the same authority and is not a limited-user alternative.

The root-owned identity record is /etc/devctrl/tooling-user.json; it contains only username/UID/GID/home. The helper is /usr/local/lib/devctrl/tooling-user.py. Runtime data lives under that user's ~/.local/share/devctrl and survives SSH logout/reboot. Native host execution uses a user systemd service and a private Unix socket, without a network port or host-execution access for project containers.

Already prepared ordinary account

Use --rootless when the remote account has no root or sudo access and already runs its own Docker Rootless daemon:

curl -fsSL https://devctrl.dev/install.sh | sh -s -- \
  'https://github.com/devctrldev/devctrl.git' 'developer@remote-server' \
  --rootless --import none

Add --import github,claude,codex only for the accounts you deliberately want to import. Add --users to enable controller-managed users. Rootless mode cannot be combined with --install-prerequisites.

This extends the existing standalone installer. It never runs sudo, installs packages, changes the system Docker daemon or firewall, installs global AppArmor profiles, or enables privileged nested Docker.

Prepared host

The SSH account needs Linux, Python 3.9+, Git, Compose v2 and a running Docker Rootless daemon. Its private local Unix socket must belong to the account. Either select its existing Docker context or set DOCKER_HOST=unix:///run/user/<uid>/docker.sock in the SSH environment.

Preflight verifies Docker's rootless security option, the selected socket and the actual daemon's UID/GID maps through /proc. At least 65,536 subordinate IDs must be mapped, covering devctrl's isolated runtime accounts. Docker-group access to a rootful daemon does not satisfy this check. Remote TCP/SSH Docker endpoints, shared sockets and unverifiable mappings are rejected.

The daemon must already have a lifecycle that survives SSH logout and restarts on host boot. devctrl does not configure systemd user services or enable lingering. See the official Docker Rootless setup and daemon lifecycle/resource-limit notes.

Storage and networking

Everything devctrl installs lives under the remote account's ~/.local/share/devctrl:

The execution directory has the same absolute path on the host and inside the host-agent. Docker CLI and SDK use the same explicitly mounted rootless Unix socket. Account ownership changes happen inside Docker's verified user namespace, never through host sudo or privileged containers.

Controller, host-agent and web gateway use a private infrastructure bridge. The controller and gateway publish only 127.0.0.1:8787 and 127.0.0.1:8788 on the remote host. The public tunnel runs remotely in the gateway; sessions and web control continue after the laptop disconnects. Ports must be available before installation.

Agent workspaces retain their separate networks and use authenticated Unix brokers for managed APIs. Tenant containers are not attached to the control-plane bridge. RootlessKit's host-network mode is not treated as physical host networking.

The installer-generated private .devctl/rootless.env keeps maintenance commands on the selected daemon and Compose profile. From the installed source directory, use the existing ./devctl commands. Automatic root/sudo bootstrap uses this profile under the dedicated account; explicit --rootful retains the original rootful profile.

Node.js is not required on the SSH host: Compose locking reuses the installed controller image. ./devctl web start, stop and status operate on the existing remote web container; stopping it leaves agent sessions running.

Aggregate hard limits

Rootless Docker does not automatically provide verifiable aggregate per-user limits. Hard-limit launches remain blocked until the host proves the required delegation. Choosing admission-only mode is advisory accounting, not kernel enforcement. A zero disk budget does not require a hard disk cap; unavailable usage is shown as unknown rather than zero.

An operator with an already prepared delegated systemd/cgroup/quota setup may pass a private JSON file:

chmod 600 ./prepared-server-cgroups.json
curl -fsSL https://devctrl.dev/install.sh | sh -s -- \
  'https://github.com/devctrldev/devctrl.git' 'developer@remote-server' \
  --rootless --users --rootless-capabilities ./prepared-server-cgroups.json

This uses the existing DEVCTL_SERVER_CGROUP_CONFIG loader. The installer does not create delegation, filesystem quotas or systemd slices. It privately transfers the configuration, binds its explicitly selected existing cgroup/proc views and system/user buses, and optionally binds a pre-existing operator-owned command wrapper for the prepared bridge or namespace-specific bus authentication. Enforcement clients ship in the host-agent image; no host packages or services are installed. Runtime checks still verify daemon mode, namespace/ownership, placement, resource limits and quota support; the presence of a file is not a capability proof.

The configuration must use placementDriver: "systemd", rootlessDelegation: true, systemd.user: true, and dataRoot matching this installation's absolute execution directory. See the server controller implementation for the enforcement contract and current limitations.

Tests

The default tests use fixture Docker responses, local Unix sockets and synthetic /proc metadata. They check namespace/socket selection, private credential transport, absence of sudo/system changes for prepared accounts, bootstrap account collision/retry behavior, legacy-install refusal, environment isolation, subordinate ID allocation and private bridge/loopback configuration.

DEVCTL_TEST_ROOTLESS_EGRESS=1 python3 -B docker/rootless-egress.integration.py runs the real egress contract against an immutable official Docker Rootless fixture (29.9.1). It loads the local test image offline and verifies allowed/denied proxy traffic, direct IP/IPv6/DNS/proxy bypass, RootlessKit/host gateway isolation and managed-service connectivity. The outer fixture has bounded CPU/memory/processes, no host mounts or published ports, and no external network; its containers/volumes are removed afterward. It does not install onto a live server or use provider credentials.