# 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](/ai/sandboxes/faq/governance/monitor-and-enforce/sign-in-enforcement/),
and [audit logs](/ai/sandboxes/faq/governance/audit). These
[organization governance features](/ai/sandboxes/faq/governance) require a separate paid
subscription —
[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-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](/ai/sandboxes/faq/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](/ai/sandboxes/faq/governance/access-controls/organization/). This
feature requires a separate paid subscription —
[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-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.

| Domain                                             | Description             |
| -------------------------------------------------- | ----------------------- |
| https://login.docker.com                           | Authentication          |
| https://hub.docker.com                             | Docker Hub              |
| https://api.docker.com                             | Docker API              |
| https://marlin-2.docker.com                        | Telemetry               |
| https://marlin-api.docker.com                      | Telemetry               |
| https://registry-1.docker.io                       | Docker pull/push        |
| https://auth.docker.io                             | Registry authentication |
| https://dhi.io                                     | Docker Hardened Images  |
| https://sbx-diagnostics.s3.us-east-1.amazonaws.com | Diagnostics upload      |

## 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:

```console
$ 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](/ai/sandboxes/faq/usage/#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](/ai/sandboxes/faq/governance/access-controls/network/),
[credential isolation](/ai/sandboxes/faq/security/isolation/#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`:

```yaml {title="claude-safe/spec.yaml"}
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/`. See
[Sandbox kits](/ai/sandboxes/faq/customize/kits/#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:

```text
/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. Use `sbx skills add` to install skills
from a Git repository, or run `sbx skills import` to copy skills from supported
host directories. `sbx` keeps the skills in a persistent store shared with
sandboxes. See [Share agent skills](/ai/sandboxes/faq/workflows/agent-skills/) for repository
management, supported host 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:

```console
$ 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:

```console
$ 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:

```text
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](/ai/sandboxes/faq/configuration/credentials/#where-secrets-are-stored).