Devboxes CLI
Sign in, run a local runner, dispatch work, follow sessions, and expose MCP tools.
The devboxes CLI uses one account and runner config. Hosted Devboxes needs no
--api; bare devboxes prints help and never starts a runner.
Sign in and register a runner
Install the CLI, then run:
devboxes login
devboxes connect [--name <runner-name>]login opens browser approval. connect uses a saved runner key, then a valid
login session, then runner approval. A rejected key can re-register only its
saved machine identity; without that identity it fails closed. Both commands
write the owner-only platform config.json.
Dispatch requires an owner or admin role and accepted beta terms. If an account
command reports an expired session, run devboxes login again.
Run tasks on this machine
devboxes credentials setup
devboxes doctor
devboxes doctor --live
devboxes doctor --json
devboxes listen [--max-concurrent <count>]credentials setup connects a subscription, stores an API key, or saves a
local auth-file reference. doctor checks registration, Docker, and credential
readiness. --live also refreshes stored subscriptions against their vendors.
--json prints one machine-health document. listen polls for matching work;
the default concurrency is one.
See Managing credentials before syncing a local credential to the organization.
Dispatch a task
devboxes dispatch "Fix the retry backoff" --repo owner/name
devboxes dispatch https://github.com/owner/name/issues/123
devboxes dispatch owner/name#123An issue reference uses the Implement GitHub Issue blueprint. Free text uses the selected blueprint. The target project is chosen in this order:
| Selection | Result |
|---|---|
--project <id> | Uses that project |
--repo <owner/name> | Matches the project's repository |
| Git remote | Matches the current directory's origin |
| Single project | Uses the organization's only project |
An inferred choice is announced and overridable with explicit flags. The model
flag is --model <provider/model>; omitting it uses the server default. Other
flags are --branch <branch> (default main), --title, --blueprint, and
--json. Devboxes rejects unavailable and unlisted models before queueing.
Follow a session
devboxes status <agentSessionId> [--json]
devboxes result <agentSessionId> [--json]status is agent-session status and always requires the ID returned by
dispatch; machine status belongs to doctor. result adds the final agent
output and pull request URL. It exits non-zero while the session is not
terminal, so scripts can poll until it succeeds.
The same run appears under Agent sessions.
MCP and automation
devboxes mcp serves dispatch_task, get_session_status, and
get_session_result over stdio using the saved login.
Shared flags are --config, --api, --auth, and --organization. Piped
approval prints the URL; BROWSER=none does the same in a terminal. --json
commands print one document on stdout.
Configuration lists environment variables, precedence, and the shared config migration.
Next: Dispatch from Slack — creating the same runs from a channel mention.