Every devhost command, explained.

Concepts

Three words carry the whole tool.

Global flags & exit codes

These work on every command.

Quick start

On the Mac mini, from a clone of the repository, ./bootstrap.sh installs the tools, builds devhost, then runs init, apply --dry-run and apply. After that:

# your main login
$ devhost account add --name personal --default --git-email me@example.com
# a second login: prints a URL, open it anywhere, sign in, paste the code
$ devhost account add --name business --git-email me@work.example
# one project, with its own Remote Control service
$ devhost env create --account business --name acme-api --repo git@github.com:acme/api.git
$ devhost doctor   # everything green?
$ devhost top      # live view, works over SSH from a phone

The environment now shows up in the Claude app under the business account and comes back by itself after a reboot.

Set up the machine

init

A short wizard that writes ~/.config/devhost/config.yaml. It asks about three things (hostname, Docker runtime, Tailscale) and generates a random ntfy topic for notifications. Without a terminal it uses the flags and defaults.

apply

Makes this Mac match the config. It is idempotent: run it as often as you like, and only what differs is changed. Any existing file is backed up first, every sudo is announced with its reason, and it is safe to interrupt and re-run.

The steps, in order:

$ devhost apply --dry-run          # read the plan
$ devhost apply                    # do it
$ devhost apply --only agents       # after changing agent choices
$ devhost apply --only env.acme-api

config

Read and change the config file. Every write is validated against the schema first, comments are preserved, and a backup is kept. Changing the config does not apply it: run devhost apply afterwards.

$ devhost config get /machine/hostname
$ devhost config set /machine/hostname mini
$ devhost config validate

update

Updates Claude Code and moves everything onto it. It upgrades the claude-code cask, restarts every Remote Control service (they run from a versioned path the upgrade deletes) and lists the sessions that were open; each continues as soon as you write in it on claude.ai. It waits while a session is in the middle of a turn, and refuses to run from inside a session of a service it would restart.

The collector can do this by itself inside claude.updateWindow (default 02:00–06:00) when claude.update is auto.

uninstall

Removes what devhost installed: launchd jobs (including orphaned com.devhost.* ones), the managed shell and git blocks, and generated files. It never touches your projects, Claude config dirs or credentials.

Accounts & projects

account

list shows each account with its login state and environment count.

add creates the account's config, settings, routing and git identity, then starts the login. A second account prints a URL: open it on any device, sign in, paste the code back.

remove <name> is refused while the account has environments. It never deletes the root, the config dir or credentials; --logout also signs the account out.

login

Signs an account in (again), accepts workspace trust and the one-time Remote Control confirmation for each of its environments, and restarts their services. Use it when doctor reports an expired login.

The first sign-in records which claude.ai login the account belongs to. A sign-in as anyone else is signed out again and refused, because the environments would otherwise register under the wrong claude.ai account. --switch-login accepts a new login on purpose and makes the account's environments register afresh.

env

An environment is one project with its own Remote Control service.

$ devhost env create --account business --name acme-api --repo git@github.com:acme/api.git --spawn worktree
$ devhost env logs acme-api -f
$ devhost env delete acme-api --delete-files

With docker.idleSleepMinutes (default 60) the collector puts an environment to sleep after an hour with no session and wakes it with the next one. A service you stopped by hand stays stopped.

agents

Shows the subagent catalog (built-in explorer, reviewer, test-runner, docs, plus your agents.custom) and which agents each account and environment has. To change them, set agents: [name, …] on an account or environment with config set, then run devhost apply --only agents. Only files devhost marked are ever changed.

session

reattach brings an ended Remote Control session back (for example after a reboot) by running it again in its worktree, once, as a one-shot service. It usually is not needed: writing in the session on claude.ai continues it under the environment's service. It only works for sessions a service started in its own worktree.

handoff prints a summary of a session so you can continue its work in a new one: the note written since the session's last activity, or, with --new, a fresh one. The note is written by a one-off fork of the session, which costs about one cache write of its context. The collector writes one on its own for a session that has been idle for 55 minutes, just before its prompt cache expires.

Watch it run

doctor

Read-only health checks, each with a one-line fix: ✅ fine, ⚠️ worth a look, ❌ broken. Exits 1 if any check fails. It reads the service logs too, so an expired login shows up as devhost login <account>. Plugins add their own checks as plugin.<name>.<check>.

status

A one-screen summary of the host, its accounts and environments.

dash & top

dash prints a snapshot of sessions, tokens, cost and CPU/RAM; with --json it is the data behind the desktop app's dashboard. --follow streams a new snapshot every sample interval (NDJSON with --json). The filters narrow it to one account, environment or model.

top is the same data as a refreshing terminal table. It works over SSH, so you can check the server from a phone. --once prints once and exits.

notify

Sends a test notification through your ntfy topic, so you know alerts reach your phone. Alerts cover memory, disk, cost limits, a restart loop and an expired login. The default relay is the public ntfy.sh; set notify.server to use your own.

collector

The collector is the one long-running process: it receives Claude Code telemetry and hook calls on 127.0.0.1:4318, samples CPU, RAM, Docker, disk and Tailscale, and stores everything in a local SQLite database. launchd runs it for you; run starts it in the foreground for debugging, and logs shows its log. It listens on localhost only and requires a bearer token.

More

storage

Keep project data on an external work volume instead of the internal disk.

plugin

Plugins add actions, checks and dashboard cards. See the plugins page for what exists and how to build one.

version

Prints the CLI version, the --json contract version, the commit it was built from, and the Node and platform it runs on.