R.3
Settings keys, environment variables, and paths
Every key that sbx settings list printed on 2026-10-08, every environment variable both tools read, and every path they use on macOS, each with its source.
sbx settings list printed 31 keys on the capture machine, every one with SOURCE default (our source record). A value comes, in order, from the environment variable of the key, then a user override written with sbx settings set, then the built-in default. RESTART yes means that daemon-side consumers that already exist need sbx daemon restart, while new sandboxes and supported CLI clients use the new value at once. The CLI table cuts long descriptions. The Meaning column completes them from the docs settings page where the page has an entry. Where the page has none, the column says so and gives the full text of sbx settings list --json (the capture).
The settings keys
| Key | Type | Default | Restart | Meaning |
|---|---|---|---|---|
claude.remoteControl | bool | false | no | Let the /remote-control channel of Claude Code authenticate with its own session token instead of the proxy swapping in the host credential (docs) |
clipboard.imagePaste | bool | false | no | Let sandboxed agents read host clipboard images, so a screenshot pastes with Ctrl+V (docs) |
diagnostics.autoUpload | string | empty | no | Consent for automatic diagnostics uploads after daemon errors: yes, no, or empty for no decision yet (docs) |
env.rememberHostCommands | bool | false | no | Ask about the host commands of an environment file only when they change, after a first approval (docs) |
kit.allowExtractedAgents | bool | true | no | Admit the pinned kit references of agents that moved out of sbx into kits, even outside kit.allowedSources, and exempt them from kit.requireSignature (docs) |
kit.allowLocalKits | bool | true | no | Allow kits from local directories and ZIP files (docs) |
kit.allowedSources | json | ["docker.io/"] | no | JSON array of allowed remote kit source prefixes, matched on a path segment boundary. ["*"] allows any source (docs) |
kit.ignoreTransparencyLog | bool | false | no | Verify keyless kit signatures without a Rekor entry, for kits signed with --tlog-upload=false (docs) |
kit.requireSignature | bool | false | no | Reject unsigned kits and kits signed by an untrusted signer. ZIP kits cannot carry a signature and are rejected (docs) |
kit.trustedSigners | json | identities ending in @docker.com through the Google issuer | no | JSON array of signer policies: a keyless identity with its issuer, or a public key file (docs) |
mcp.forceLocalGateway | bool | false | yes | Use the local MCP gateway when the account would otherwise use the hosted one (docs) |
model.providers | json | {} | no | JSON object of inference endpoints for sbx run --model, each with url, wire, and apiKeyEnv (docs) |
no_proxy | string | empty | yes | Shared proxy exception list for sandbox, daemon, and supported CLI traffic (docs) |
no_proxy.daemon | string | empty | yes | Exception list for daemon and CLI requests only. A non-empty value replaces the shared list for that scope (docs) |
no_proxy.sandbox | string | empty | yes | Exception list for sandbox egress only. A non-empty value replaces the shared list for sandboxes (docs) |
platform.allowExperimentalFeatures | bool | true | no | Allow experimental features. The CLI text is complete. The docs say the default is false (conflict C18) |
platform.images.registryMirror | string | empty | no | Mirror host for template and kit references that resolve to Docker Hub, without a URL scheme (docs) |
platform.images.useDHI | bool | false | no | Use the Docker Hardened Image variant dhi/sbx-templates:<tag> for the default agent templates (docs) |
proxy | string | empty | yes | Upstream proxy for sandbox, daemon, and CLI traffic: an HTTP, HTTPS, or SOCKS5 URL, a PAC source, system, or direct (docs) |
proxy.daemon | string | empty | yes | Upstream proxy for daemon requests and supported CLI requests only (docs) |
proxy.integratedAuth | bool | false | yes | NTLM or Kerberos authentication with the Windows sign-in identity. No effect on macOS or Linux (docs) |
proxy.sandbox | string | empty | yes | Upstream proxy for sandbox egress only. It overrides proxy for that scope (docs) |
sandbox.disk.dockerVolume | string | 10g | no | Size of the /var/lib/docker volume of a new sandbox, at least 512 MiB. Existing volumes keep their size (docs) |
skills.defaultMode | string | readonly | no | Mode of the shared skills store when --skills is omitted: readonly, readwrite, or off (docs) |
ssh.agentForwardingEnabled | bool | true | yes | Let clients forward an SSH agent into sandboxes. Private keys stay on the host (docs) |
ssh.agentSocketPath | string | empty | yes | Fixed host SSH agent socket path. Empty uses the socket each client supplies (docs) |
ssh.autoCreate | bool | false | yes | Create a sandbox on SSH connect when it does not exist. The docs have no entry (conflict C20) |
ssh.defaultAgent | string | shell | yes | Built-in agent used for SSH auto-created sandboxes. The docs have no entry |
ssh.defaultTemplate | string | empty | yes | Template image override for SSH auto-created sandboxes (agent default if empty). The docs have no entry |
ssh.workspaceRoot | string | empty | yes | Host directory holding SSH auto-created sandbox workspaces (empty = mount-less, container-internal). The docs have no entry |
tls.allowNegativeSerial | bool | false | yes | Accept server certificates with a negative serial number, as some TLS-inspecting proxies issue (docs) |
Value types are bool, int, float, string, and json, and an override that conflicts with an administrator constraint is rejected. Most changes apply within about five seconds.
Keys the docs name that the CLI did not print
The docs settings page, three guides, and one release note name keys that sbx settings list did not return (conflict C19). The manual prints them here and nowhere else.
| Key | Where the docs use it | What the docs say |
|---|---|---|
feature.model | the local model guide | sbx settings set feature.model true after platform.allowExperimentalFeatures true turns on sbx run --model |
feature.sandbox-gpu | the GPU guide | the same pair of commands reveals the hidden --gpu flag |
feature.udp-egress | the network policy page | the same pair of commands allows sbx policy allow network --protocol udp |
diagnostics.autoUploadErrorCooldownInDays | the settings page | integer, default 1, the number of days between automatic uploads, applied only when diagnostics.autoUpload is yes |
feature.ssh | the v0.34.0 release note | sbx settings set feature.ssh true enables the experimental native SSH endpoint |
Environment variables that sbx reads
These variables configure the host side. They never set a variable inside a sandbox, and the daemon reads them only when it starts.
| Variable | Sets |
|---|---|
DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE | clipboard.imagePaste |
DOCKER_SANDBOXES_CLAUDE_REMOTE_CONTROL | claude.remoteControl |
DOCKER_SANDBOXES_USE_DHI | platform.images.useDHI |
DOCKER_SANDBOXES_KIT_ALLOWED_SOURCES | kit.allowedSources |
DOCKER_SANDBOXES_KIT_ALLOW_LOCAL | kit.allowLocalKits |
DOCKER_SANDBOXES_KIT_ALLOW_EXTRACTED_AGENTS | kit.allowExtractedAgents |
DOCKER_SANDBOXES_KIT_REQUIRE_SIGNATURE | kit.requireSignature |
DOCKER_SANDBOXES_KIT_TRUSTED_SIGNERS | kit.trustedSigners |
DOCKER_SANDBOXES_KIT_IGNORE_TLOG | kit.ignoreTransparencyLog |
DOCKER_SANDBOXES_PROXY | proxy.sandbox, sandbox traffic only |
DOCKER_SANDBOXES_NO_PROXY | no_proxy.sandbox, sandbox traffic only |
DOCKER_SANDBOXES_SSH_AUTO_CREATE | ssh.autoCreate |
DOCKER_SANDBOXES_SSH_DEFAULT_AGENT | ssh.defaultAgent |
DOCKER_SANDBOXES_SSH_DEFAULT_TEMPLATE | ssh.defaultTemplate |
DOCKER_SANDBOXES_SSH_WORKSPACE_ROOT | ssh.workspaceRoot |
DOCKER_SANDBOXES_MODEL_PROVIDERS | model.providers |
DOCKER_SANDBOXES_ALLOW_EXPERIMENTAL_FEATURES | platform.allowExperimentalFeatures |
DOCKER_SANDBOXES_TLS_ALLOW_NEGATIVE_SERIAL | tls.allowNegativeSerial |
HTTP_PROXY, HTTPS_PROXY, NO_PROXY, and their lowercase forms | the upstream proxy when no proxy or no_proxy setting is set |
DOCKER_SANDBOXES_DOCKER_SIZE | the Docker data disk size of one creation, such as 30g |
DOCKER_SANDBOXES_ROOT_SIZE | the root filesystem size of one creation, such as 40g |
DOCKER_SANDBOXES_CLONED_WORKSPACE_SIZE | the size of the private clone of a --clone sandbox |
DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE | 0 turns off the virtiofs cache of the workspace mount |
SBX_NO_TELEMETRY | 1 turns off CLI usage analytics |
DOCKER_ACCESS_TOKEN | the Docker identity of sbx env commands, with a state scope per token |
SBX_MCP_URL | none selects the local MCP data plane instead of the hosted gateway |
SANDBOXES_STORAGE_ROOT | not documented in the vendored sources. The research notes name it from the v0.29.0 release note, whose body the vendored release list does not keep |
Host lifecycle commands of an environment file receive SBX_LIFECYCLE_PHASE, SBX_ENV_FILE, SBX_ENV_FILES, SBX_ENV_DIR, SBX_SANDBOX_NAME, SBX_AGENT, and SBX_WORKSPACE. After a cloud creation they also receive SBX_SANDBOX_ID.
Environment variables that docker-agent reads
The rename of v1.30.0 changed the prefix from CAGENT_ to DOCKER_AGENT_, and the old names stay accepted (conflict C53).
| Variable | Legacy name | Meaning |
|---|---|---|
DOCKER_AGENT_DATA_DIR | none | The data directory, the same as --data-dir. Added in v1.147.0. |
DOCKER_AGENT_CONFIG_DIR | CAGENT_CONFIG_DIR | The config directory, the same as --config-dir. Added in v1.100.0. |
DOCKER_AGENT_MODELS_GATEWAY | CAGENT_MODELS_GATEWAY | Route model traffic through a gateway, the same as --models-gateway |
DOCKER_AGENT_DEFAULT_MODEL | CAGENT_DEFAULT_MODEL | The model used when none is given, as provider/model |
DOCKER_AGENT_HIDE_TELEMETRY_BANNER | CAGENT_HIDE_TELEMETRY_BANNER | 1 hides the first-run telemetry notice only |
TELEMETRY_ENABLED | none, no prefix | false turns telemetry off (conflict C67) |
DOCKER_AGENT_AUTO_UPDATE | none | 1, true, yes, or on lets a standalone release binary update itself. Added in v1.74.0. |
DOCKER_AGENT_NO_TOKEN_EXCHANGE | none | 1 stops the exchange of the docker login access token for a Docker token |
DOCKER_AGENT_HUB_LOGIN_URL | none | Point the token exchange at a Docker staging environment, HTTPS docker.com URLs only |
DOCKER_AGENT_AUTO_INSTALL | none | false turns off automatic tool installation from the aqua registry |
DOCKER_AGENT_TOOLS_DIR | none | The directory of installed tools, default ~/.cagent/tools/ |
DOCKER_AGENT_NO_SETUP | none | 1 stops the setup wizard from being offered when no model is usable |
DOCKER_AGENT_BOARD_EDITOR | BOARD_EDITOR, kept for one release | The editor the board opens a worktree in, default code |
DOCKER_AGENT_PPROF_ADDR | CAGENT_PPROF_ADDR | A loopback address for a Go pprof server. The docs still print the legacy name |
DOCKER_AGENT_ENCRYPT_KEY | none | The key of share push --key and share pull --key |
GITHUB_TOKEN | none | Raises the GitHub API rate limit of the auto-installer |
CAGENT_ASKPASS_SOCKET, CAGENT_ASKPASS_TOKEN | none, still prefixed CAGENT_ | The sudo bridge of the shell toolset, set only on commands that call sudo |
CAGENT_EXP_DEBUG_LAYOUT, CAGENT_HIDE_TELEMETRY | renamed in v1.30.0 | The new names are not documented in the vendored sources |
Provider credential variables such as ANTHROPIC_API_KEY are listed in R.6.
Paths on macOS
The capture machine runs macOS, so the table gives macOS paths first and the Linux and Windows forms where the docs state them. Replace rohitghumare with your user name.
| Path | Holds | Tool |
|---|---|---|
~/Library/Application Support/com.docker.sandboxes/ | the sbx state directory, removed as a last resort after sbx reset | sbx |
.../com.docker.sandboxes/sandboxes/sandboxd/sandboxd.sock | the Unix socket of sandboxd | sbx |
.../com.docker.sandboxes/sandboxes/sandboxd/daemon.log | the daemon log | sbx |
.../com.docker.sandboxes/sandboxes/agent-skills | the shared skills store. Linux ~/.local/state/sandboxes/sandboxes/agent-skills, Windows %LOCALAPPDATA%\DockerSandboxes\sandboxes\state\agent-skills | sbx |
~/Library/Logs/com.docker.sandboxes/sandboxes/auditkit/ | audit records written by the daemon. Linux ${XDG_STATE_HOME:-~/.local/state}/sandboxes/sandboxes/auditkit/, Windows %LOCALAPPDATA%\DockerSandboxes\sandboxes\logs\auditkit\ | sbx |
~/.config/sbx/credentials.yaml | the credential bindings file. Windows %APPDATA%\sbx\credentials.yaml | sbx |
| the macOS Keychain | the secret store behind sbx secret set. Windows uses the Credential Manager, Linux the Secret Service, or the file ~/.config/com.docker.sandboxes without one | sbx |
~/.sbx/run/d/containerd/containerd.sock.ttrpc | the containerd ttrpc socket the daemon binds at start, named in the error the capture recorded | sbx |
~/.sbxenv.yaml | a base environment file merged under every project file | sbx |
/opt/homebrew/Caskroom/sbx/0.47.0/Sbx.app/Contents/MacOS/sbx | the CLI binary of the Homebrew cask, with mkfs.erofs under Contents/libexec | sbx |
~/.local/state/sandboxes/, ~/.cache/sandboxes/, ~/.config/sandboxes/ | the three Linux state directories, under XDG_* when set. Windows uses %LOCALAPPDATA%\DockerSandboxes | sbx |
~/.config/cagent/config.yaml | user settings, aliases, global permissions and hooks, board projects | docker-agent |
~/.config/cagent/.env | the env file that docker agent setup writes provider keys into | docker-agent |
~/.config/cagent/hooks.d/ | hook drop-in files, loaded in lexicographic order | docker-agent |
~/.cagent/ | the data directory, which holds session.db, worktrees, and plans | docker-agent |
~/.cagent/session.db | every session, as SQLite | docker-agent |
~/.cagent/cagent.debug.log | the debug log, with --debug | docker-agent |
~/.cagent/tools/bin/ | binaries the aqua auto-installer downloads | docker-agent |
~/.cagent/plans/, ~/.cagent/session_plans/ | shared plans and per-session plans | docker-agent |
~/.cagent/memory/<config-name>/memory.db | the default database of the memory toolset | docker-agent |
~/.cagent/themes/<name>.yaml | custom TUI themes | docker-agent |
<data-dir>/runs/<pid>.json | the discovery record of a run started with --listen | docker-agent |
~/Library/Caches/cagent/ | the cache directory on macOS | docker-agent |
~/Library/Caches/cagent/sandbox-kits/<hash> | the kit that run --sandbox stages, keyed by the agent reference | docker-agent |
| a private file under the cache directory | the cached Docker bearer token. Its name is not documented | docker-agent |
~/.codex/skills/, ~/.claude/skills/, ~/.agents/skills/, and the project .claude/skills/, .github/skills/, .agents/skills/ | the SKILL.md directories docker-agent discovers | docker-agent |
The directories of docker-agent keep the name cagent after the rename (conflict C54). Nothing migrates state from the plugin-era directories ~/.docker/sandboxes/ and ~/.sandboxd/ to the sbx state directory (conflict C17).
Docker Sandboxes (sbx) and Docker Agent (docker-agent) sbx 0.47.0, docker-agent 1.149.0 · bf4169c · 2026-10-07 · Edition 2026.10