Configuration

Hosted Devboxes works without configuration. Use this reference for unattended runners, alternate profiles, or a self-hosted deployment.

Flags and commands

Shared configuration flags apply before or after a command:

Flag	Purpose
`--config <path>`	Use an alternate account and runner config
`--api <url>`	Override the Devboxes API base URL
`--auth <url>`	Override the browser-approval auth URL
`--organization <id>`	Select an organization

devboxes connect --name <name> is the only command with a machine-name flag. devboxes listen --max-concurrent <count> defaults to one task. devboxes doctor --live tests stored subscriptions against their vendors, and doctor --json prints the merged machine status.

Flags override environment variables, which override the config file. The hosted API default is https://api.devboxes.ai/api; self-hosted URLs must use HTTPS, except loopback HTTP for local development.

Environment variables

Variable	Purpose
`DEVBOX_API_BASE_URL`	API base URL
`DEVBOX_AUTH_BASE_URL`	Browser-approval auth URL
`DEVBOX_ORGANIZATION_ID`	Organization selection
`DEVBOX_CLI_SESSION_TOKEN`	Terminal session for unattended account commands
`DEVBOX_RUNNER_API_KEY`	Runner key for unattended `connect`
`DEVBOX_RUNNER_NAME`	Machine name used by `connect`
`DEVBOX_OPENCODE_DOCKER_SOCKET_PATH`	Local Docker socket or Windows named pipe
`DEVBOX_OPENCODE_CONFIG_DIR`	Opencode config copied read-only into task containers
`DEVBOX_OPENCODE_HOME_ROOT`	Host root for per-task secret files

DOCKER_HOST is a fallback only for a local unix:// or npipe:// socket. Remote Docker TCP endpoints are rejected. Without an override, the runner uses /var/run/docker.sock or the Windows Docker named pipe.

Shared config

Account and runner state share ~/.config/devboxes/config.json or its XDG/platform equivalent. The CLI writes it atomically with mode 0600; the default directory uses 0700.

The file holds API and auth URLs, organization, terminal session, machine identity, machine name, runner API key, and local credential references. Unknown keys survive a write so an older CLI does not erase newer settings. The age-encrypted device credential store sits beside the config.

The config contains credentials. Never paste it into an issue or support request. Use devboxes doctor --json for a secret-free machine-health document, but redact its paths, URLs, organization ID, and error details before sharing it.

Preserve an existing runner identity

The unified CLI does not read listener.json. Rename it in the same platform config directory: $XDG_CONFIG_HOME/devboxes or ~/.config/devboxes on Linux, ~/Library/Application Support/devboxes on macOS, and %APPDATA%\devboxes on Windows. The Linux default is:

mkdir -p ~/.config/devboxes
mv ~/.config/devboxes/listener.json ~/.config/devboxes/config.json
devboxes login

The unchanged machine ID, runner API key, and credential references keep the same machine identity. devboxes login adds the terminal session to that file. Do not run connect against an empty config first: that registers a different machine.

Automation output

Failures exit non-zero; cancelling an interactive prompt exits 130.
doctor exits 1 when any readiness check needs attention.
dispatch, status, result, doctor, and credentials status accept --json and write one JSON document to stdout.
credentials setup --api-key <provider> reads stdin when piped, keeping the key out of the process list.
Piped approval flows print their URL. BROWSER=none forces the same behavior.

See Managing credentials before automating sync, and Troubleshooting for recovery.

Next: Security — the trust boundary around runner hosts and credentials.