FAQ

Is Docker Sandboxes free? Can I use it commercially?

Yes to both. The sbx CLI is free to use, including for commercial and professional work, with no per-seat fee. Install it, sign in with a free Docker account, and run sandboxes at no cost.

The only paid component is organization governance: centrally managed network, filesystem, and MCP policies, sign-in enforcement, and audit logs. These organization governance features require a separate paid subscription — contact Docker Sales to get started. Everything else, including running agents in isolated sandboxes, is free.

Why do I need to sign in?

Docker Sandboxes is built around the idea that you and your agents are a team. Signing in gives each sandbox a verified identity, which lets Docker:

• Tie sandboxes to a real person. Governance matters when agents can build containers, install packages, and push code. Your Docker identity is the anchor.
• Enable team features. Team-scale features like organization governance, shared environments, and audit logs need a concept of "who," and adding that later would be worse for everyone.
• Authenticate against Docker infrastructure. Sandboxes pull images, run daemons, and talk to Docker services. A Docker account authenticates those requests.

Your Docker account email is only used for authentication, not marketing.

Can I enforce sandbox policies across my organization?

Yes. Admins can centrally manage network, filesystem, and MCP policies. These controls apply to every sandbox in the organization. When organization governance is active, only organization allow rules grant access: local allow rules set with sbx policy are no longer evaluated, while local deny rules still apply on top.

See Organization policies. This feature requires a separate paid subscription — contact Docker Sales to get started.

Which domains do I need to allow for Docker Sandboxes to work?

If your organization restricts outbound network access with a firewall or proxy, add the following domains to your allowlist so that sbx can authenticate, pull images, and report diagnostics.

Does the CLI collect telemetry?

The sbx CLI collects basic usage data about CLI invocations:

• Which command you ran
• Whether it succeeded or failed
• How long it took
• If you're signed in, your Docker username is included

Docker Sandboxes doesn't monitor sessions, read your prompts, or access your code. Your code stays in the sandbox and on your host.

To opt out of all analytics, set the SBX_NO_TELEMETRY environment variable:

$ export SBX_NO_TELEMETRY=1

How do I set custom environment variables inside a sandbox?

Starting with sbx version 0.39.0, use -e/--env or --env-file with sbx run and sbx create. See Set environment variables for syntax, precedence rules, persistent configuration for an existing sandbox, and guidance for credentials.

Variables in /etc/sandbox-persistent.sh are available to interactive sessions and agents started with sbx run. A variable only takes effect for sessions and agents started after it's added. Restart a running agent, or stop and start the sandbox, to pick up the new value.

Why do agents run without approval prompts?

The sandbox itself is the safety boundary. Because agents run inside an isolated microVM with network policies, credential isolation, and no access to your host system outside explicitly shared paths, the usual reasons for approval prompts (preventing destructive commands, network access, file modifications) are handled by the sandbox isolation layers instead.

If you prefer to re-enable approval prompts, change the permission mode inside the session. Most agents let you switch permission modes after startup. In Claude Code, use the /permissions command to change the mode interactively.

To make approval prompts the default for every session, define a custom sandbox kit that overrides the agent's entrypoint to drop the permission-skipping flag. For example, a kit that launches Claude Code without --dangerously-skip-permissions:

schemaVersion: "1"
kind: sandbox
name: claude-safe
sandbox:
  image: "docker/sandbox-templates:claude-code-docker"
  entrypoint:
    run: [claude]

Run it with sbx run claude-safe --kit ./claude-safe/. See Sandbox kits for the full pattern.

How do I know if my agent is running in a sandbox?

Ask the agent. The agent can see whether or not it's running inside a sandbox. In Claude Code, use the /btw slash command to ask without interrupting an in-progress task:

/btw are you running in a sandbox?

Why doesn't the sandbox use my user-level agent configuration?

Sandboxes don't import your complete user-level agent configuration. Hooks, settings, and other files under directories such as ~/.claude remain on the host. Project-level configuration in the working directory remains available inside the sandbox.

Shared agent skills are the exception. Run sbx skills import to copy skills from supported host directories into a persistent store shared with sandboxes. See Share agent skills for the supported directories, mount behavior, and per-sandbox opt-out.

Keep project-specific skills and other agent configuration in the project itself. This versions the configuration alongside the code. Don't use symlinks to host paths because a sandboxed agent can't follow them outside the sandbox.

Can I paste images into an agent?

Yes, but it's off by default. Text paste already works, because the terminal sends it directly. Pasting an image or screenshot with Ctrl+V is different: the agent reads it from your host clipboard, and the sandbox blocks that access unless you opt in.

Turn it on with a local setting:

$ sbx settings set clipboard.imagePaste true

Ctrl+V then pastes host images into agents that read the clipboard, including Claude Code and Codex. The setting takes effect within a few seconds, even for running sandboxes.

This is opt-in because it relaxes the sandbox's isolation: when enabled, a process inside the sandbox can read your host clipboard through the host-side proxy. The exposure is narrow — reads happen only on a paste, return image data only (image/png), and clipboard content is never cached or logged — but it's still host data crossing into the sandbox, so it stays off until you turn it on.

To turn it back off:

$ sbx settings set clipboard.imagePaste false

Can I use Docker Sandboxes on headless Linux?

Yes. On Linux, sbx stores secrets in the Secret Service exposed by your desktop keyring, such as GNOME Keyring or KDE Wallet. Headless servers and some WSL setups have no running Secret Service, so sbx falls back to a file under $XDG_CONFIG_HOME/com.docker.sandboxes, which defaults to ~/.config/com.docker.sandboxes when $XDG_CONFIG_HOME is unset. No setup is required. When you store a secret on such a host, sbx prints a notice:

No keychain detected - this secret will be stored on disk, protected by file permissions rather than a password

sbx stores the file in a directory with 0700 permissions, the same file-permission model used for ~/.docker/config.json. Any user or process that can read the file can retrieve the stored credentials, so treat the directory as sensitive. Where available, prefer a keychain, which mediates access per application.

To keep secrets in a keyring instead, run a Secret Service on the host before storing them: install gnome-keyring and start dbus-run-session, or run the keyring daemon under a login session that unlocks it. Once a working Secret Service is available, sbx stores new secrets in the keychain again. For where each platform keeps secrets, see Where secrets are stored.