{"slug": "how-secrets-work-in-docker-sandboxes-local-vs-cloud", "title": "How Secrets Work in Docker Sandboxes: Local vs Cloud", "summary": "Docker Sandboxes keep real API keys out of the agent's reach by routing requests through a proxy that injects stored credentials, with secrets held in the OS keychain for local sandboxes and in Docker's cloud secret store for cloud sandboxes. Local secrets are added with `sbx secret set anthropic` and take effect in running sandboxes immediately, while cloud secrets must be set with `sbx --cloud secret set` before the sandbox launches. Docker maintains three separate, non-sharing secret stores: `sbx secret` for local sandboxes, `sbx --cloud secret` for CLI-created cloud sandboxes, and the Docker Agentic Platform web interface.", "body_md": "# How Secrets Work in Docker Sandboxes: Local vs Cloud\n\nDocker Sandboxes keep your API keys out of the agent’s reach. Here is how secrets work in local and cloud sandboxes, and how they differ.\n\nIn both local and cloud sandboxes, the agent never holds your real API key. A proxy sits between the sandbox and the internet, and it adds the real credential to each request on the way out.\n\nHere is what happens when an agent like Claude Code calls its model provider:\n\n1. The agent sends a request from inside the sandbox. It only has a placeholder value, such as `proxy-managed` .\n2. The proxy catches the request and checks the destination (for example, `api.anthropic.com` ).\n3. If that destination matches a known service, the proxy looks up your stored secret and writes the real value into the auth header.\n4. The request goes to the provider with the real key. The sandbox never sees it.\n\nThe main difference between local and cloud is **where the proxy runs and where the secret is stored**. Locally, both live on your own computer. In the cloud, both live in Docker's cloud.\n\n## **Local sandboxes**\n\nIn a local sandbox, your secrets stay on your own computer. The proxy runs on your host and reads them from your OS keychain.\n\n## **Local sandbox architecture**\n\nYour key sits in the OS keychain. The sandbox only sees `proxy-managed`, and the proxy on your host adds the real key when a request leaves for an allowed host.\n\n**Where secrets are stored**\n\n- macOS: the system Keychain\n- Windows: Windows Credential Manager\n- Linux: your desktop keyring, such as GNOME Keyring or KDE Wallet\n- Headless Linux or some WSL setups: a file in `~/.config/com.docker.sandboxes` , protected only by file permissions\n\n**How to add a secret**\n\nRun `sbx secret set anthropic` and paste your key when asked. Secrets are global by default, so every sandbox can use them. To limit a secret to one sandbox, add `--sandbox my-sandbox`. A sandbox-scoped secret wins over a global one.\n\nChanges take effect in running local sandboxes right away. You do not need to restart them.\n\n**Other ways to provide a value**\n\n- **Dynamic sources:** use`--ref` for a 1Password reference or AWS Secrets Manager ARN, or`--command` to run a command on the host. The value is fetched on the host, and the sandbox still gets only the placeholder.\n- **Import:**`sbx secret import` reads matching environment variables, such as`ANTHROPIC_API_KEY` .\n- **Custom secrets:**`sbx secret set-custom` ties a value to a domain and an environment variable, for APIs that are not built-in services.\n\n**OAuth (sign in instead of an API key)**\n\nSome agents let you sign in with your account instead of pasting a key. The sign-in runs on your host, so the token never enters the sandbox.\n\n- **Codex:** run`sbx secret set openai --oauth` . A browser opens on your host and the token is saved in your keychain.\n- **Claude Code:** use`/login` inside Claude Code. The sandbox gets placeholder tokens, and refreshes go through the proxy.\n- **Cursor and Droid:** they ask you to sign in when the agent starts. There is no way to do it ahead of time.\n\nIf both an API key and OAuth are set for the same service, the API key wins.\n\n## **Cloud sandboxes**\n\nIn a cloud sandbox, your secrets live in Docker's cloud secret store. A cloud proxy adds them to requests, so they stay outside the sandbox filesystem.\n\n**Cloud sandbox architecture**\n\nSame idea, but the secret store and proxy run in Docker's cloud. You set secrets from your laptop with `sbx --cloud secret set` before you start the sandbox.\n\n**Set it up before you launch.** Add the credential first, then start the sandbox:\n\n```\nsbx --cloud secret set anthropic\nsbx --cloud run claude --name cloud-project\n```\n\n**Three separate secret stores**\n\nThese do not share secrets with each other:\n\n- `sbx secret` for local sandboxes\n- `sbx --cloud secret` for cloud sandboxes created with the CLI\n- The Docker Agentic Platform web interface, which has its own secrets\n\nA key you saved locally will not show up in the cloud. You need to add it again with `--cloud`.\n\n**Scope**\n\nCloud secrets use **account scope** by default, so every cloud sandbox in your Docker account can use them. To limit an API key to one sandbox, add `--sandbox cloud-project`. Set a sandbox-scoped secret before you create the sandbox.\n\n**OAuth in the cloud is limited**\n\n- **Claude Code:** needs an Anthropic API key. Claude subscription sign-in is not supported through the cloud store.\n- **Codex:** can use`sbx --cloud secret set openai --oauth` . This works at account scope only.\n- **Droid:** API key only. Cloud-managed OAuth is not supported.\n\n**Custom secrets**\n\nFor an API that is not built in, use `set-custom`:\n\n```\nsbx --cloud secret set-custom --name project-api \\\n  --host api.example.com --env PROJECT_API_TOKEN\n```\n\nThe sandbox gets a placeholder in `PROJECT_API_TOKEN`. The cloud proxy adds `Authorization: Bearer <secret>` to every request sent to that host. Use `--header` and `--format` to change the header.\n\n**Not supported in the cloud:** registry credentials, and the dynamic `--ref` and `--command` sources. As a workaround, an environment file with `snapshot: true` can fetch a value once and upload it as a fixed cloud secret.\n\n## **Local vs cloud at a glance**\n\n## **Common mistakes and good habits**\n\n- **Expecting local secrets in the cloud.** They are separate. Run`sbx --cloud secret set` for anything a cloud sandbox needs.\n- **Signing in inside a cloud sandbox.** An agent's own sign-in can write credential files into the sandbox. Those files can end up in templates and`sbx move` snapshots. Use the cloud secret store instead, or sign out and delete the files before you capture or move the sandbox.\n- **An API key hiding your subscription.** If an API key and OAuth are both set for the same service, the API key wins. Remove the key if you want to use your subscription sign-in.\n- **Turning on OAuth passthrough.** A kit can set`passthrough: true` , which sends the real token into the sandbox. Only do this when you really need it, because it removes the protection.\n- **Global registry credentials.** Registry credentials stay on your host, but with --all-sandboxes the proxy lets every sandbox log in to that registry. Give access only to the sandboxes that need it with --sandbox <name>.\n- **Headless Linux storage.** Without a keyring, secrets sit in a file that any process with read access can open. Use a keyring where you can.", "url": "https://wpnews.pro/news/how-secrets-work-in-docker-sandboxes-local-vs-cloud", "canonical_source": "https://www.ajeetraina.com/how-secrets-work-in-docker-sandboxes-local-vs-cloud/", "published_at": "2026-11-02 02:39:05+00:00", "updated_at": "2026-11-22 15:49:32.139782+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-safety"], "entities": ["Docker", "Docker Sandboxes", "Claude Code", "Anthropic", "OpenAI", "Codex", "Cursor", "Droid"], "also_reported_by": [], "takeaway": "Route agent API calls through a proxy that swaps a `proxy-managed` placeholder for the real key at the destination host, so the sandbox never holds the credential and local secret changes apply without restarting running sandboxes.", "recommendation": {"advice": "Store agent API keys in the host keychain or Docker's cloud secret store and let a destination-checking proxy inject them, so sandboxes only ever see a `proxy-managed` placeholder.", "playbook": "agent-security", "playbook_url": "https://wpnews.pro/playbooks/agent-security"}, "alternates": {"html": "https://wpnews.pro/news/how-secrets-work-in-docker-sandboxes-local-vs-cloud", "markdown": "https://wpnews.pro/news/how-secrets-work-in-docker-sandboxes-local-vs-cloud.md", "text": "https://wpnews.pro/news/how-secrets-work-in-docker-sandboxes-local-vs-cloud.txt", "jsonld": "https://wpnews.pro/news/how-secrets-work-in-docker-sandboxes-local-vs-cloud.jsonld"}}