GUIDE · HOW-TO 11 min ·

Keep API keys out of a Docker sandbox coding agentsbx secret, scoped, with no env flags

Docker Sandboxes can keep a key on the host and let a proxy write it into the agent's outbound requests. That holds only if you store keys with sbx secret, scope each one to the sandbox that needs it, and stop passing values in with -e or --env-file.

TL;DR· the answer, in twenty seconds

What happened: When a November 17 Hacker News thread asked how to run coding agents without handing them credentials, one of the first replies pointed at Docker Sandboxes' sbx secret set. Docker's design keeps the key on the host and has a proxy write it into the agent's outbound HTTP headers, while the agent sees a placeholder.

The minimum fix: Store each key with sbx secret set, preferably as a --ref or --command source, scope it with --sandbox, drop every -e KEY and --env-file from your sbx run line, and keep helper scripts out of the mounted workspace.

The lesson: The proxy hides the value. It does not narrow what the agent can do with it, and it cannot help a credential that travels over plain TCP.

Docker Sandboxes runs a coding agent in a microVM and keeps the agent's API keys on the host. A proxy on the host rewrites the auth header of each outbound request, so the agent inside sees a placeholder. That is the design. Whether your keys stay out of the VM depends on how you hand them over, and the sbx CLI gives you several ways to hand them over that skip the proxy.

The question came up on November 17, when a post titled "Running coding agents without handing them my credentials" reached the Hacker News front page. One of the first replies, from ryanczak, was one line: "Docker sandboxes support secret injection," with a link to the sbx secret set reference. Another commenter quoted the custom-secret docs, one said they now run agents only inside sbx, and another called it "the obvious solution to at least 80%" of the complaints in the thread. The top comment, from saagarjha, took the other side: hiding the key while giving the agent everything the key enables adds ceremony and little else. Both are right, and this guide covers each half.

I worked from Docker's documentation for Docker Sandboxes v0.54.0, released November 16, which I read on November 21. I did not install sbx for this guide; it requires a Docker sign-in, and I wanted every claim here to trace to a page you can open. Treat the commands as the documented interface, and check them against sbx --help on your version.

How the proxy keeps the key out of the VM

Docker's architecture page describes the path. All outbound TCP from the sandbox goes through a proxy on your host. HTTP and HTTPS go through a forward proxy, which enforces network policy and handles credential injection. Other TCP traffic "is forwarded transparently." When the agent calls a provider, the request leaves the microVM carrying a sentinel value. The host proxy checks the destination against policy, looks up the stored credential, and rewrites the header after the request has left the VM.

The credentials page lists four forms a credential can take:

  • Stored secrets, set with sbx secret set <service>, held in your OS keychain and keyed by a service name such as anthropic, openai or github.
  • Custom secrets, set with sbx secret set-custom, keyed to one or more hostnames and an environment variable name. Docker marks the command experimental.
  • OAuth, a host-side sign-in for agents that support it, such as Claude Code, Codex, Cursor and Droid.
  • Registry credentials, set with sbx secret set --registry, for pulling images and kits.

Each built-in service maps to a fixed list of domains. The proxy injects the anthropic key into requests to api.anthropic.com, console.anthropic.com, claude.ai and mcp-proxy.anthropic.com. github covers api.github.com, github.com, raw.githubusercontent.com, gist.github.com and two Copilot hosts. Keep that list in mind; it comes back in the last section.

On macOS the store is the system Keychain. On Linux it is the Secret Service from GNOME Keyring or KDE Wallet. On a headless Linux host with no Secret Service, sbx falls back to a file under ~/.config/com.docker.sandboxes in a 0700 directory and prints "No keychain detected." Docker's docs say any user or process that can read that file can read the credentials. If you run sandboxes on a build box, that file is your secret store, and it deserves the same care as ~/.docker/config.json.

Store each key with sbx secret, scoped to one sandbox

Three choices matter when you store a key: where the value comes from, which sandboxes can use it, and how long the host caches it.

Start with the source. A literal value works, but sbx can also store a reference and resolve it on the host when the proxy needs it. --ref takes a 1Password op:// reference or an AWS Secrets Manager ARN. --command runs a host command and uses its standard output. With either, the keychain holds the pointer and the value lives in the tool that already manages it.

Then the scope. Service secrets are global by default, which means every sandbox on the machine gets the key, including the one you made last week to try a third-party kit. Pass --sandbox to bind a key to one sandbox. A sandbox-scoped secret takes precedence over a global one for that sandbox.

Then the cache. The host caches resolved service secrets for 55 minutes by default. --refresh on-demand resolves the source on every use, and --refresh 15m shortens the window.

A setup for one project looks like this. Create the sandbox without attaching, store the keys against its name, then run the agent:

# Create the sandbox for this repo without opening a session
sbx create --name billing-api claude ~/src/billing-api

# Model key from 1Password, resolved on the host, bound to this sandbox
sbx secret set anthropic --sandbox billing-api \
  --ref 'op://Work/Anthropic/credential' --refresh 15m

# GitHub token from the host gh login, resolved on every use
sbx secret set github --sandbox billing-api \
  --command 'gh auth token' --refresh on-demand

# Confirm what this sandbox can use
sbx secret ls --sandbox billing-api

sbx run --name billing-api

The sbx create --name <name> <agent> <path> form comes from Docker's own example. Add --clone if you want the agent working on a private clone with your repository mounted read-only, instead of a read-write bind mount. Docker's docs say adding, updating or removing a service secret takes effect in existing local sandboxes without a restart, including --ref and --command secrets.

If you have to type a value, use the prompt or standard input. Docker's own reference labels the --token flag on sbx secret set "less secure: visible in shell history." For custom secrets, the docs warn that --value "$API_KEY" still exposes the value in process arguments even though the shell expanded it. Pipe it instead:

printf '%s' "$SENTRY_AUTH_TOKEN" | sbx secret set-custom \
  --sandbox billing-api \
  --host sentry.io \
  --env SENTRY_AUTH_TOKEN \
  --value-stdin

Inside the sandbox, SENTRY_AUTH_TOKEN holds a generated placeholder such as sbx-cs-<rand>. When a process sends a request to sentry.io with the placeholder in a header, the proxy swaps in the real token. Docker states the limit: "Replacement applies only to HTTP request headers, not request bodies."

sbx secret import reads keys such as ANTHROPIC_API_KEY and GH_TOKEN from your current shell and writes them to the keychain as global secrets. It is a fast migration, and it leaves two things behind. Every imported key is global, so rescope the ones that should not be. The keys are also still exported in your shell profile, where every other process you start can read them. Remove them from ~/.zshrc or ~/.bashrc once the import is done, and rotate any key that was ever in a profile you synced to a dotfiles repo.

Where a raw value still gets in

The proxy only sees what goes through sbx secret. Four paths put the real value inside the VM, and each one is easy to fall into.

The first is environment flags. sbx run -e KEY=VALUE, a bare -e KEY that copies the value from your current shell, and --env-file all set variables inside the sandbox. The sbx run reference says these apply to the agent session and are "baked into the sandbox when this run creates it." That is the raw value, readable by the agent, by any package it installs, and by anything that ends up in its transcript. If your sbx run line carries --env-file .env because that is how you ran containers for years, the proxy never touches those keys. Variables in /etc/sandbox-persistent.sh inside the VM are the same case.

The second is the workspace. Docker's default posture page says sbx run mounts the current directory when you pass no path, and the agent "can read, write, and delete any file within that directory, including hidden files." A .env, a terraform.tfvars or a service-account JSON in the repo is in the VM the moment the sandbox starts. Docker also offers clone mode, which mounts your repository read-only and gives the agent a private clone, and a mountless mode with no host workspace. Neither changes the rule: whatever the agent can read, it can send.

The third is OAuth passthrough. The credentials page says a kit can set passthrough: true on its OAuth config to opt out of sentinel masking, which "sends the real token response into the sandbox and reduces credential isolation." Built-in kits need no approval for their credentials. Third-party kits need an approved binding in ~/.config/sbx/credentials.yaml, and sbx asks for it the first time you run one. Read the kit's credential declaration before you approve it, and treat a passthrough flag as a reason to say no.

The fourth is any protocol the proxy does not rewrite. Injection lives in the HTTP forward proxy. Postgres, MySQL, Redis, SMTP and SSH to a custom port travel as plain TCP, so a database password has to exist inside the VM in readable form for the client to send it. The same goes for AWS SigV4, where the secret key signs the request and never appears in a header. SSH is the exception Docker handles: agent forwarding is on by default, and the docs say processes in the sandbox can request signatures but "can't read or copy a private key."

Here is a quick check you can run inside a sandbox you already use. It lists variable names that look like credentials, and prints the first characters of each value, so you can tell a placeholder from a real key without dumping the key to your terminal:

sbx exec billing-api sh -c \
  'env | grep -Ei "key|token|secret|pass|auth|url" | sed -E "s/=(.{0,8}).*/=\1.../"'

A value that starts with sbx-cs- or reads proxy-managed came from the proxy. A value that starts with sk-, ghp_, AKIA or postgres:// came in raw, and you should find out which flag or file put it there.

Keep the helper commands out of the agent's reach

--command is the most useful source and the easiest to get wrong. The daemon stores the command text and replays it on the host whenever the cached value expires. If that command runs a script the agent can edit, the agent can change what runs on your host, outside the VM, with your user's access.

Docker changed how this works in v0.53.0, released November 11. The release notes say built-in secret reference providers now run host tools from a temporary directory and ignore empty or relative PATH entries. The sbx secret set reference spells out the consequence for command secrets: relative references such as ./helper "no longer resolve against the project or daemon working directory." It also says sbx "does not copy helpers, inspect their dependencies, or confine their execution," and that helpers and anything they load must stay outside writable sandbox mounts.

Read that as three rules:

# Unsafe: the helper sits in the repo the agent can write to
sbx secret set-custom --host api.example.com --env EXAMPLE_KEY \
  --command '/Users/me/src/billing-api/scripts/get-key.sh'

# Unsafe: a version manager that picks the op binary from a project file
# (.tool-versions or mise.toml inside the workspace)

# Safer: an absolute path the sandbox never mounts
sbx secret set-custom --host api.example.com --env EXAMPLE_KEY \
  --command '/usr/local/libexec/creds/get-example-key'

The first rule is the one in the docs: absolute paths only, outside every writable mount. The second follows from the v0.53.0 note about version managers. If asdf or mise resolves op or aws from a project-level config, the agent can edit that config and choose which binary the daemon runs. Docker says to set provider versions in your global config. The third is about mounts added later. The reference warns that broad mounts exposing host configuration stay unsafe, "including mounts added to a running sandbox later." If you mount ~/.config or your home directory into a sandbox to share some setting, every helper and provider config under it is now writable from inside.

Environment files carry the same risk. A sbxenv.yaml can declare lifecycle, secret and MCP commands that run on your host, and Docker says to keep it outside writable sandbox mounts so the agent cannot change what a later invocation runs. That includes a file you checked into the repo you mounted.

A hidden key still works for the agent

saagarjha's critique holds against this design too. The proxy writes your GitHub token into every request the sandbox sends to github.com, api.github.com and gist.github.com. An agent that reads a poisoned issue can push to any repository the token can push to, or create a secret gist with whatever it read from your workspace. It never learns the token string. It does not need to.

Three settings narrow what the key can do.

Scope the token itself. A fine-grained GitHub token limited to one repository and the permissions the task needs is a smaller blast radius than the gh auth token output from your personal login, which carries every scope you ever granted. --command 'gh auth token' is convenient because it needs no setup, and that convenience covers every repository you can touch. For a sandbox that works on one repo, create a token for that repo and store it with --ref from your password manager.

Scope the network. Docker's defaults block outbound TCP unless a rule allows the destination. sbx policy allow network adds rules for every sandbox by default; pass --sandbox to keep them local. HTTP rules accept --method, --path and --query, so you can allow api.github.com for GET on /repos/your-org/billing-api/** and leave the rest blocked. Docker's own help notes a limit: hostname blocking can fail when an allowed host and a denied host share an IP address. Check a rule with sbx policy check network, which as of v0.54.0 names the rule that allowed a target.

Scope the sandbox. A global secret reaches every sandbox, including one running a kit you have not read. sbx secret ls with no flags shows the scope column for each entry. Anything marked (global) that only one project uses should move.

None of this stops an agent from misusing a key you allowed it to use. That is the gap saagarjha pointed at, and the answer is a smaller key plus a log of what it did, not a better hiding place.

What this means for your stack

If you already run agents in Docker Sandboxes, the minimum action takes one sitting. Run sbx secret ls and rescope every global secret that only one sandbox needs. Search your shell history and scripts for sbx run lines with -e or --env-file and replace them with stored secrets. Move every --command helper to an absolute path outside your mounts. Run the env check above in each sandbox you use, and rotate any key that turns up raw.

The pattern underneath is that the host should resolve a credential where the agent cannot reach, at the moment of use, and hand it to the narrowest thing that needs it. Docker's proxy does that for HTTP requests leaving a VM. For the credentials it cannot rewrite, the database password and the signing key, the same rule means running the step that needs them outside the agent's process tree, with the value injected into that one child process.

hasp is one working implementation of that second half on the host. hasp run --project-root . --env DATABASE_URL=@DATABASE_URL --grant-secret window --grant-window 15m -- npm run db:migrate gives the migration process the connection string while the agent's command line carries only the reference name. Source-available (FCL-1.0), local-first, macOS and Linux, no account.

Whichever tools you use, keep the two questions apart. Where the key sits decides who can steal it. What the key allows decides what an agent can do with it on a bad day, and no proxy answers that one for you.

Sources· cited above, in one place

NEXT STEP~90 seconds

Stop handing the agent your real keys.

hasp keeps secrets in one local encrypted vault, brokers them into the child process at exec, and never lets the agent read the value.

  • Local, encrypted vault — no account, no cloud, no telemetry by default.
  • Brokered run — agent gets a reference, the child process gets the value.
  • Pre-commit + pre-push hooks catch managed values before they ship.
  • Append-only HMAC audit log answers "did the agent touch the prod token?" in seconds.
→ okvault unlocked · binding ./api
→ okgrant once · pid 88421
→ okagent never read

macOS & Linux. Source-available (FCL-1.0, converts to Apache 2.0). No account.

Browse all clusters· eight threads, one index