Install a standalone remote console
The installer uses Local Docker when called without arguments. Use this mode to run devctrl on this computer, or supply a repository and SSH destination for a remote installation.
Local Docker (default)
Use macOS, Linux or WSL2 with a running Linux Docker engine, Docker Compose 2.24.4 or newer, Git, tar, curl, Python 3.9 or newer, and Node.js 24.22.1 or newer in the 24.x line or 26.12.1 or newer in the 26.x line. SSH and a remote server are not required. The installer keeps the selected local Docker context without changing Docker's global context.
With an authorized product checkout, start the installer without arguments:
DEVCTL_INSTALL_SOURCE_DIR=/absolute/devctrl-checkout \
sh /absolute/devctrl-checkout/install.sh
When the canonical product source is publicly accessible, the same default is:
curl -fsSL https://devctrl.dev/install.sh | sh
The explicit --local-docker option remains available. To select another local
Docker context, pass --docker-context NAME. After installation, use the saved
local launcher:
devctrl local tui
devctrl local web
devctrl local status
Connect GitHub or GitLab accounts after local installation. Read a token from a private file through stdin; do not put the token in command arguments:
devctrl local git connect github --login example-user --token-stdin < PRIVATE_GITHUB_TOKEN_FILE
devctrl local git connect gitlab --login example-user --token-stdin < PRIVATE_GITLAB_TOKEN_FILE
Alternatively, use --token-env with a token already provided privately in the
process environment. GitHub checks GH_TOKEN then GITHUB_TOKEN; GitLab checks
GITLAB_TOKEN, GITLAB_ACCESS_TOKEN then OAUTH_TOKEN. The account is associated
with the signed-in user; importing it does not grant other users access to it or
replace project permissions.
The bootstrap's credential-import and SSH options belong to remote installation and cannot be combined with Local Docker mode. The remaining sections describe the remote installation path.
Remote server installation
Install the devctrl controller, execution host and browser gateway on a fresh Ubuntu/systemd server. The installer also adds a small SSH launcher on your computer so you can open the terminal interface.
Connect as root or with passwordless sudo for initial setup. The installer adds missing dependencies and creates a separate limited OS tooling account with private Rootless Docker 29.9.1+. Management tools then run under that account, without sudo or rootful Docker-group access. If you already have a prepared ordinary account, use `--rootless` to install without system changes.
Docker builds and the repository checkout happen on the server. After setup, you can close your laptop and SSH connection; the remote services keep running.
Source access is a prerequisite. At the 2026-10-21 check the canonical repository was not anonymously readable. With an authorized checkout, use its own installer and explicitly supply that checkout as the product source:
DEVCTL_INSTALL_SOURCE_DIR=/absolute/devctrl-checkout \
sh /absolute/devctrl-checkout/install.sh 'YOUR_PROJECT_REPOSITORY_URL' 'remote-server'
The checkout path must exist on the computer running this command. The project repository argument is separate from the devctrl source. Review the existing credential import options for a private project. This source-checkout path is a documented installer input; a new production installation was not performed as part of the website verification.
When the canonical product source is publicly accessible, the bootstrap can run from any directory without a local product checkout:
curl -fsSL https://devctrl.dev/install.sh | \
sh -s -- 'https://github.com/devctrldev/devctrl.git' 'remote-server'
Replace the repository argument with your own repository and remote-server with your SSH alias, hostname, IPv4 address, user@host (for example, root@203.0.113.10) or user:password@host. Quote the entire destination when it contains a password. For a custom SSH port or IPv6 destination, configure an alias in ~/.ssh/config; inline ports and ssh:// URLs are not accepted. The script itself always comes from devctrldev/devctrl; the repository argument selects the Project to launch, not the installer source. Download and inspect the script first if preferred. The landing publishes the unchanged script at https://devctrl.dev/install.sh, which is also the URL used by its copy button. The repository raw URL https://raw.githubusercontent.com/devctrldev/devctrl/main/install.sh is an alternative download source; the Project/SSH arguments are identical.
The anonymous curl command requires the repository to be public. A private GitHub repository returns 404 without authentication; changing visibility and deploying DNS/hosting are separate publication steps.
For local testing before publishing changes, use DEVCTL_INSTALL_SOURCE_DIR=/absolute/checkout by setting that variable for sh -s -- in the curl pipeline. DEVCTL_INSTALL_SOURCE_ARCHIVE_URL remains available for explicitly supplied source archives; production installation defaults to cloning the canonical GitHub repository at main.
For a disposable SSH destination on your Mac, see the installer lab (source access required).
Start from a local Git folder
Pass a folder instead of a repository URL to set up both the remote server and the existing local Exchange client:
curl -fsSL https://devctrl.dev/install.sh | \
sh -s -- './my-project' 'remote-server'
The folder can be relative, absolute, a linked Git worktree, or a subdirectory of a checkout. The installer finds its Git root and reads origin (or the only configured remote if there is no origin). Credential-free HTTPS and standard git@HOST:OWNER/REPOSITORY.git / ssh://git@HOST/... remotes are accepted; SSH Git remotes become HTTPS for the server checkout. A custom SSH Git port cannot be assumed to be the HTTPS port. Set an HTTPS origin for nonstandard Git transports. Missing/ambiguous remotes fail before server setup.
The server clones that repository normally, on its default branch. The installer then invokes the same local-client setup as devctrl client install, selecting the newly created Project by its actual controller ID and mapping the checkout's agent-interchange directory. It pulls the prebuilt client image and enrolls a Project-scoped credential automatically. The full working tree, uncommitted changes and unpublished commits are not uploaded. Existing Exchange files and root .gitignore policy are preserved.
This mode requires running local Docker (Docker Desktop on macOS), an unlocked SSH agent containing the server key, and a trusted directly reachable SSH destination. These requirements are checked before any server changes or credential reads. Password-only SSH cannot keep the background file client connected. A symlinked Exchange directory is rejected. A connection with existing local client settings is preserved: choose another --remote-name NAME rather than replacing its mappings. --no-launcher is incompatible with local-folder setup.
With a repository URL, no local client is installed and local Docker is not required. In either mode, importing Git or coding-agent authorization remains a separate explicit selection. The folder does not authorize credential transfer. Setup offers GitHub, GitLab or both, then GitLab.com or a custom HTTPS host and port. Saved GitLab PAT profiles can be imported through glab; short-lived OAuth tokens and their refresh state are not portable through this import. Claude and Codex support their existing local import paths, while Antigravity uses native remote sign-in. See Git providers for platform, private-host and authentication limits.
The custom GitLab authority configures account/API access. It does not provision workspace networking. A restricted workspace needs a Project Network hostname grant for a public custom server on 443; its gateway supports public HTTP/HTTPS on ports 80/443 only. Private destinations and other ports, including 8443, remain unavailable through that gateway even after account authorization, host checkout or credential import. Launch identity/credential checks do not establish container reachability.
If client installation fails after successful server setup, the server and launcher remain available. The error prints a devctrl client install NAME --project PROJECT_ID=FOLDER recovery command; fix the local Docker/SSH prerequisites and run it instead of repeating fresh server installation. Closing or sleeping the laptop pauses Exchange; remote sessions keep running.
Requirements and consent
Local requirements are sh, ssh, git, tar and Python 3.9+. URL-based setup requires no local Docker, Node, pnpm or controller; folder-based setup also requires Docker and an unlocked SSH agent for its local client. Source is fetched into a temporary directory and removed after installation. URL-based setup leaves only the self-contained ~/.local/bin/devctrl launcher and private SSH connection metadata locally; use --no-launcher to omit both. Folder-based setup additionally retains the client container, scoped credential and synchronization state described in local client setup. Default installer source is the real https://github.com/devctrldev/devctrl.git repository at main.
The SSH destination must already work with a trusted known_hosts entry, using root or passwordless sudo. Without an inline password, installer SSH calls use BatchMode=yes: prepare key authentication (including a locally unlocked ssh-agent key) before installation; SSH password and key-passphrase prompts are disabled even without --non-interactive. With user:password@host, the installer removes the password from the destination before logging or calling SSH and supplies it through SSH_ASKPASS. It temporarily creates a private directory (0700), password file (0600) and helper (0700), then removes them after each SSH call, including failures. Password mode allows one password prompt and disables public-key and keyboard-interactive authentication. Strict host-key checking and disabled agent forwarding apply in both modes. The remote SSH server must allow password authentication; this does not provide a sudo password.
An inline password is still visible in the command you enter, potentially in shell history and the initial shell/Python process arguments. Prefer key authentication when avoiding that exposure matters. The password is not added to child SSH arguments, environment values, installer logs or persistent account state. These SSH credentials authenticate the server connection; the separately selected GitHub token authenticates repository access and never belongs in the SSH destination or repository URL. The server needs Ubuntu, Python 3, Docker Engine, Compose v2 and Git. Loopback ports 8787 and 8788 must be free. Public access uses outbound Cloudflare quick-tunnel with the existing localhost.run fallback; no provider registration is needed. Availability of these external tunnel providers is not guaranteed.
Missing server Docker Engine, Compose v2, BuildKit/buildx, Git, curl and CA certificates are installed automatically on Ubuntu through root or passwordless sudo. Minimal Ubuntu images also receive Python before the Python preflight. Already available packages are reused; an existing Docker daemon is not reinstalled or restarted merely because Git or a plugin is missing. The installer does not modify firewall rules. Package installation and the first image/runtime builds can take several minutes.
For a prepared server where package installation should be disabled:
curl -fsSL https://devctrl.dev/install.sh | \
sh -s -- REPOSITORY_HTTPS_URL SSH_ALIAS --no-install-prerequisites
The old --install-prerequisites flag remains accepted for compatibility. Explicit --rootless requires a prepared Docker daemon and never installs system packages. The default root bootstrap creates and prepares its limited account automatically. --rootful explicitly selects the legacy trusted profile (including non-systemd labs), with root-equivalent Docker authority; it is not a limited-user installation.
Before writing remote files or reading credential values, preflight refuses an existing /opt/agent-yard, /var/lib/devctl-console, /var/lib/devctl, existing devctl* containers or occupied required ports. This is a fresh installation command, not an upgrade, migration or host takeover command. Existing servers should be connected through their existing console or a separately supported migration flow.
Connect GitHub and agent accounts
Claude and Codex can import selected local credentials. Antigravity uses its official sign-in inside the remote CLI; this installer does not import its local login.
Discovery checks the normal local files ~/.claude/.credentials.json and $CODEX_HOME/auth.json (default ~/.codex/auth.json). On macOS, if the Claude file is absent, it checks for the Claude Code-credentials Keychain entry without reading its value. Claude's email is displayed from ~/.claude.json → oauthAccount.emailAddress when present. It is a display hint, not a credential validity check. A selected authorization's JWT email claim may supply a missing label; token contents are never printed. Otherwise the installer honestly reports that the identity is unavailable.
For GitHub.com repositories, an installed gh is queried with `gh auth status --hostname github.com --json hosts`. Discovery prints saved successful account logins, host and the active marker. It does not export any token. Environment overrides (GH_TOKEN, GITHUB_TOKEN, enterprise equivalents and GH_DEBUG) are removed from these subprocesses so a saved-account selection cannot silently use a different token or enable secret-bearing debug output. Custom GitHub Enterprise hosts are not yet supported by the installed GitHub provider. GitLab imports use the selected GitLab provider and its account login; see the explicit token options below.
Interactive setup asks exactly which discovered providers to import. Pressing Enter imports none. The prompt uses /dev/tty, so the curl | sh form still works. --import github,claude is explicit consent to transfer those two selected credentials; codex can also be included. Without an explicit token input, selection of an undiscovered provider fails. For GitHub, the active successful saved account is selected by default; --github-account LOGIN selects another discovered login and requires GitHub import consent. The installer prints the selected account plan, identities and destination server before transfer.
For unattended installation, default to no transfer:
curl -fsSL https://devctrl.dev/install.sh | \
sh -s -- REPOSITORY_HTTPS_URL SSH_ALIAS --non-interactive --import none
Or explicitly authorize selected imports and a GitHub account:
curl -fsSL https://devctrl.dev/install.sh | \
sh -s -- https://github.com/OWNER/PRIVATE_REPOSITORY.git SSH_ALIAS \
--non-interactive --import github,claude --github-account YOUR_LOGIN
Only after this selection does `gh auth token --hostname github.com --user LOGIN` retrieve the selected token. Only selected credential material travels through SSH stdin, never command arguments, source archives, console logs, image builds or project environment files. The installer does not copy an entire home directory, transcripts, SSH keys or unselected credentials. Claude receives authorization JSON and a minimal onboarding marker. Symlinked authorization files are rejected.
On the server, authorization is stored using the existing provider account layout:
/var/lib/devctl/accounts/claude/imported-claude/.credentials.json/var/lib/devctl/accounts/codex/imported-codex/auth.json
Files are mode 0600; each account directory is mode 0700 and owned by the UID returned by the existing runtime's accountRuntimeIdentity. Provider parent directories are explicitly mode 0711 so that the account UID can traverse them. The displayed identity is recorded in the imported account alias, and imported Claude/Codex accounts become the Project defaults for their provider. No agent is automatically launched. Imported accounts are registered through the existing account/presence APIs with status unknown until the provider validates them on use. Importing a file cannot renew expired OAuth or prove a subscription is currently usable. Existing local authorization remains unchanged.
Only the conventional active local account for each provider is discovered; alternative profiles, custom Claude config locations and provider credential stores without portable JSON require normal account login/import through devctrl.
Supply GitHub or GitLab tokens explicitly
Choose minimum token permissions for your workflow and set an expiration.
For a GitHub fine-grained token, select only the repositories you need:
Metadata: Read-only and Contents: Read-only cover HTTPS clone/fetch,
Contents: Read and write covers push, and pushing .github/workflows/*
changes also needs Workflows: Read and write. For a GitLab classic token,
use read_api and read_repository for the catalog and clone/fetch, or
read_api and write_repository to push. The token owner's repository
access, organization approval and branch rules still apply.
The quickest form names the provider and account; the installer then asks for
the token in a hidden terminal prompt (it reads /dev/tty with echo off, so it
also works under curl | sh) and the token never appears in arguments, shell
history, URLs, logs or files:
curl -fsSL https://devctrl.dev/install.sh | \
sh -s -- REPOSITORY_HTTPS_URL SSH_ALIAS --github example-user
--github LOGIN stands for --git-providers github --import github
--github-account LOGIN with a prompted token; --gitlab LOGIN does the same
for GitLab (add --gitlab-host HTTPS_URL for a custom server). With only
--gitlab, the installer also offers an optional hidden prompt for a GitHub
token that can read the devctrl source.
The devctrl source repository is private. With the default github.com source,
the prompted GitHub token, --github-token-stdin or --github-token-env also
authenticates the installer's fetch of devctrldev/devctrl on your computer, which then streams
only a source archive to the server. That token then also needs read access to
devctrldev/devctrl: a fine-grained token for resource owner devctrldev
with only that repository and Metadata: Read-only plus Contents: Read-only,
or a classic token with repo. A fine-grained token covers one owner, so a
Project repository under another owner needs its account token through
--github-token-env. To fetch the source without importing a Git account (for
example for a GitLab Project), use the bootstrap-only option:
sh ./install-devctrl.sh REPOSITORY_HTTPS_URL SSH_ALIAS \
--import none --source-token-stdin --non-interactive < PRIVATE_SOURCE_TOKEN_FILE
Without a terminal (CI), combine --github LOGIN with --github-token-env, or
use the advanced flags below. Download the installer first so stdin remains
available for the token, then explicitly select the Git provider, import and
account login:
curl -fsSL https://devctrl.dev/install.sh -o install-devctrl.sh
sh ./install-devctrl.sh REPOSITORY_HTTPS_URL SSH_ALIAS \
--git-providers github --import github --github-account example-user \
--github-token-stdin --non-interactive < PRIVATE_GITHUB_TOKEN_FILE
For GitLab, use the corresponding provider and account flags:
sh ./install-devctrl.sh REPOSITORY_HTTPS_URL SSH_ALIAS \
--git-providers gitlab --import gitlab --gitlab-account example-user \
--gitlab-token-stdin --non-interactive < PRIVATE_GITLAB_TOKEN_FILE
For a custom GitLab server, also set --gitlab-host HTTPS_URL. Its workspace
network access remains a separate project policy.
Instead of redirecting stdin, use --github-token-env or --gitlab-token-env
with a token already provided privately in the environment. GitHub checks
GH_TOKEN then GITHUB_TOKEN; GitLab checks GITLAB_TOKEN,
GITLAB_ACCESS_TOKEN then OAUTH_TOKEN. Keep the matching --import and
account-login selections. Only one provider can read stdin in a single run;
use an environment token for the other provider when importing both.
Token input from stdin requires --non-interactive; the hidden prompt is the
interactive alternative. Do not pipe a token into the curl | sh command, place a token in a repository URL or pass it as an argument.
Token import is explicit account authorization, and does not bypass repository,
project or workspace network permissions.
Remote installation and Project setup
The installer streams an allowlisted source archive through SSH, excluding .devctl, .git, dependencies, built output, screenshots, environment files, provider auth files, key files and symlinks. DEVCTL_INSTALL_SOURCE_DIR=/absolute/checkout uses the current local source, including tracked/uncommitted implementation changes under the allowlist. Otherwise DEVCTL_INSTALL_SOURCE_URL and DEVCTL_INSTALL_REF select the source Git repository and branch/tag; overrides are operator-trusted code, not Project-supplied input.
Remote layout:
| Path/container | Purpose |
|---|---|
~devctrl/.local/share/devctrl/source |
Source checkout (the generated account may be named devctrl-N) |
~devctrl/.local/share/devctrl/console/database |
Controller SQLite database and encryption master key |
~devctrl/.local/share/devctrl/console/secrets |
Controller administrator and enrolled host credentials |
~devctrl/.local/share/devctrl/console/web |
Persistent browser authorization, tunnel status and IPC |
~devctrl/.local/share/devctrl/execution |
Project checkouts, isolated accounts, interchange and sessions |
~devctrl/.local/share/devctrl/host-runner |
Private native host runner socket, Node/npm runtime and static runner script |
devctl-controller-1 |
Controller API bound to remote loopback 8787 |
devctl-host-agent-1 |
Existing host agent, enrolled with its own scoped credential |
devctl-web-1 |
Built HTML client, API gateway, remote terminal transport and public tunnel |
Services use docker/standalone-rootless-compose.yaml, the same controller/host images and session/runtime implementation, and restart: unless-stopped. The user systemd manager/lingering keeps the private daemon and native host runner alive after SSH logout/reboot. Host paths match inside and outside the container. Existing rootful installs and explicit --rootful keep docker/standalone-compose.yaml, /opt/agent-yard, /var/lib/devctl-console and /var/lib/devctl; the installer never moves or restarts those workspaces automatically.
The repository argument supports credential-free HTTPS URLs. Without an explicitly imported GitHub account, the remote host clones with prompting disabled and no forwarded SSH agent. Public GitHub, GitLab and self-hosted HTTPS Git repositories work if reachable.
With --import github, the remote controller validates the selected token against GitHub's /user API and refuses an identity mismatch before storing it in the existing encrypted Git-account store. It then queues the existing authenticated host credential import and Project checkout. The existing github-import helper supplies credentials only to its exact HTTPS host, keeping the token out of Git command arguments and environment. The installer waits for this checkout result before launching the workspace. The imported account remains available in Git accounts for organization/repository browsing and future sessions. Token authorization can still be limited by repository permissions, SSO, expiry or organization policies; import does not broaden those permissions. The temporary remote source archive and Docker images never contain the token.
When checkout succeeds, the installer registers the Project, creates a main workspace pinned to the standalone host and queues its launch through the normal controller API. An existing repository .devcontainer/devcontainer.json or .devcontainer.json is preserved; otherwise the explicit managed base runtime is selected. The first runtime build continues on the server and can be observed from Projects. No agent session starts or consumes provider usage automatically; choose the imported account when launching one in the interface.
If private checkout fails, the Project is still registered and the web console is retained. Connect the appropriate Git account in Git accounts, finish repository checkout/launch through the existing workflow and inspect the error. The installer reports partial setup and exits nonzero rather than claiming the Project is ready. A public tunnel timeout similarly retains the working server and exits nonzero.
Terminal access through the local SSH launcher
After installation:
devctrl tui remote
The launcher is one standalone Python file using the standard library and system SSH. It runs the existing TUI bundle inside the server's controller container. The laptop displays its terminal through SSH; this mode does not run a local React renderer, controller, Docker or background process. It preserves terminal type/color hints and uses existing SSH configuration/host-key checks, without SSH-agent forwarding. Automatic limited-user installs retain the operator's SSH destination and dispatch Docker commands through the root-owned privilege-dropping helper. Existing rootful installs use Docker directly or passwordless sudo; prepared rootless accounts reuse their private daemon configuration. Attaching never builds images, restarts services or replaces sessions.
This SSH shortcut is for trusted server operators and uses the controller container's existing operator credential. It does not turn an SSH account into an isolated application user; regular users connect with devctrl tui connect https://console.example or web/app,
using their own invitation and then their own password. Personal HTTPS TUI needs
Node.js 24.22.1 LTS or a newer patched supported release locally; the operator SSH shortcut does not. See
personal user sign-in.
If ~/.local/bin is not already on PATH, the installer prints its full executable path and this command:
export PATH="$HOME/.local/bin:$PATH"
The installer does not edit shell startup files. Connection metadata lives in ${XDG_CONFIG_HOME:-$HOME/.config}/devctrl/consoles.json, mode 0600; it contains SSH destinations and rootless selection, never API tokens, SSH passwords or agent credentials. Password-based installations save only user@host; subsequent SSH connections authenticate normally. Existing unrelated launchers and conflicting connection names are preserved and reported before server setup.
For an already installed server, install only the local shortcut:
curl -fsSL https://devctrl.dev/install.sh | sh -s -- \
--launcher-only remote-server
This mode does not contact or modify the server. Add --rootless if that existing server uses the rootless installation. For multiple servers, use --remote-name work during installation or launcher-only setup, then devctrl tui remote work. The first connection remains the default. From a repository checkout, ./devctl tui remote [NAME] delegates to the same launcher before starting any local Docker services; ordinary ./devctl tui keeps its existing local behavior.
Inside an agent terminal, Ctrl+] detaches back to the TUI. q closes the TUI; managed agents continue running.
Local folders and Exchange
The SSH launcher itself does not mount or synchronize laptop folders. A local folder passed to initial setup automatically installs the Exchange client alongside it; a repository URL does not. Paths chosen inside a server-hosted TUI refer to the server/container, not the laptop. Browser uploads, downloads and drag-and-drop require no extra local installation and use the server Exchange API.
Install the optional prebuilt Docker client with devctrl client install. Select Projects and distinct local Exchange directories; the launcher enrolls a Project-scoped client, mounts the selected folders and connects outward to the existing controller over SSH. It needs local Docker, an unlocked SSH agent and verified server keys, without a source checkout, Node.js or second controller. Reconnect is automatic; sleeping the laptop pauses sync while server work continues.
To additionally run workloads on local Docker, explicitly use devctrl host install local. This installs a separate host-agent module with its own credential and Docker socket; the folder client itself never receives the socket. Existing local devctl installations are preserved. See local client setup for commands, supported SSH profiles, access boundaries, state paths and update/removal behavior.
See Exchange boundaries, file synchronization (source access required) and the shared UI.
Browser access and operation
devctrl web remote opens the existing remote console and prints its private HTTPS URL; --no-open only prints it. It starts the server web container when stopped and does not start a local gateway.
On successful setup, the installer prints the remote private browser URL containing ?api=REMOTE_ORIGIN#key=.... This is the remote web gateway's access key, not the controller administrator token. Treat that URL as private. The temporary tunnel hostname may change after a restart; browser installations using that hostname also depend on it.
Retrieve the current link on the server:
docker exec devctl-web-1 node docker/web-access.mjs status
Use sudo when required by server permissions. The loopback address printed by this command belongs to the server, not the laptop. The browser can connect through the public link without keeping any local component running.
To inspect services or restart after correcting prerequisites:
docker compose -f /opt/agent-yard/docker/standalone-compose.yaml ps
docker logs devctl-controller-1
docker logs devctl-host-agent-1
docker logs devctl-web-1
Logs may contain private access links; do not publish them. Database, account homes and web authorization need backups independent of the disposable source tree. Do not delete those directories to retry a failed install. Preflight intentionally refuses to overwrite partial installations; inspect and complete recovery explicitly.
The standalone profile supports the API-backed Project/session/account/grant UI and browser terminal. Legacy operator workflows that assume the original laptop/client-agent/SSH topology are not all portable yet. In particular, toolchain rollout is refused before mutations in this profile rather than attempting the laptop's upgrade plan. Remote cloud provisioning, legacy SSH account transfer and other operator integrations may require their own host credentials or topology setup; the installer does not invent those grants or claim to configure them.
Verification
python3 -B docker/bootstrap-console.test.py exercises both halves with temporary directories, fake authorization, stub SSH, mocked Docker/controller responses and no external calls. It checks consent, source exclusions, credentials on stdin, exact runtime identity reuse, private file/traversal permissions, existing-install refusal, repository fallback and the public-link result. Real temporary Git repositories cover local folders, nested paths, linked worktrees, SSH remotes and ambiguous origins. A shell-entry test runs the real bootstrap and local-client installer with stub infrastructure, verifying scoped enrollment, read-only ignore-policy mounts, Exchange-only sync and no local controller or Docker socket. Local prerequisite failures happen before server changes; client failures retain a recovery command. python3 -B docker/remote-launcher.test.py verifies standalone execution without a source checkout, Docker or Node; named connections, password omission, safe SSH arguments, rootless selection, collision preservation, launcher-only setup and automatic/opt-out package installation. python3 docker/ssh-auth.test.py checks password destination parsing, private file modes, cleanup on failures/signals, sanitized child arguments and environment, and preserved stdin. sh -n install.sh, Python compilation and docker compose -f docker/standalone-compose.yaml config --quiet verify syntax/configuration. Tests do not install onto a real server, import real credentials or create paid resources.
Reproducible installer demo
python3 docker/bootstrap-demo.py
This runs the actual install.sh, local bootstrap and remote installer code with an isolated temporary HOME and fixture GitHub (demo-maintainer) / Claude (demo@agent-yard.example) accounts. Only the SSH, Docker, GitHub and controller infrastructure boundaries are simulated. It prints the real installer steps, including discovery, the selected account plan, imports, private checkout and public console link. It never reads real local accounts, contacts a real server, builds images or starts a billable workload. AGENT_YARD_DEMO_CONSOLE_URL can point the final fixture link at a locally running demo console for a screen recording. The output explicitly identifies the infrastructure as simulated; it is not evidence of a real fresh-server deployment.
Optional application users
Add --users to the installer command to enable server-controller identities;
combine it with --rootless only on a prepared rootless host. The default remains
a single operator. Users receive separate projects, accounts, secrets, containers,
sidecars and storage, with aggregate per-user/per-host resource reservations.
Shared services require explicit publication and project grants. A configured
budget becomes a hard limit only when the host verifies the corresponding
cgroup/filesystem adapter. The installer does not migrate an existing controller
or prepare host delegation automatically.
Server users and invitations,
host enforcement, rootless setup.