Skip to content

Credentials for agents

You might run several of your own agents on one cheap machine. Each agent should be able to call only the API it needs, without receiving a real key it could read and copy. A secret grant keeps the real value on the host: the sandbox gets a placeholder, and bhatti-netd substitutes the value only in outgoing HTTPS request headers to an approved host. Use one API key per agent or per person to separate ownership and access.

A grant is not an egress rule. First give the sandbox a NIC and permission to reach the host it will call. If the sandbox has no network (the default), or its allowlist omits the target, granting the secret won’t make a connection possible.

Terminal window
bhatti secret set MODEL_KEY 'real-value'
bhatti create --name model-agent \
--allow-host api.openai.com \
--secret-grant MODEL_KEY@api.openai.com

The guest’s MODEL_KEY environment variable contains a placeholder, not the secret. Pass it as you would an ordinary token in a request header:

Terminal window
bhatti exec model-agent -- sh -c 'curl -H "Authorization: Bearer $MODEL_KEY" https://api.openai.com/v1/models'

You can repeat --secret-grant for other stored names, or write NAME@host1,host2 when a single grant needs multiple hosts. Give only the hosts you intend; a --secret-grant does not widen the network allowlist. At create time these grants have no TTL option: use secret grant below for a time-limited grant.

Terminal window
bhatti create --name github-agent --allow-host api.github.com
bhatti secret set GH_TOKEN 'real-value'
bhatti secret grant GH_TOKEN --sandbox github-agent --host api.github.com --ttl 7d

secret grant prints a grant ID and a placeholder. Unlike --secret-grant at creation, it does not inject a new environment variable into the already-running guest. Provide that placeholder to your agent as GH_TOKEN (for example, in its own runtime configuration) and have it put the placeholder in the HTTPS header. --host is required and repeatable; it accepts an exact host or *.example.com wildcard. The policy must already allow the host. --ttl accepts durations like 90m, 24h, 7d; without it, the grant lasts until revoked or the sandbox is destroyed.

If you fork a sandbox with create --from, its network policy and guest memory are copied, along with independent copies of its active grants. The fork’s grants keep the same placeholders, hosts and expiry, so copied guest env placeholders still resolve there. Inspect the fork’s grants with secret grants and revoke inherited access by its own grant IDs before untrusted work; revoking a source grant does not revoke the fork’s copy. A new secret grant adds access rather than replacing an inherited grant.

Terminal window
bhatti secret grants
bhatti secret revoke <grant-id>
# In non-interactive automation:
bhatti secret revoke <grant-id> -y

grants includes active, expired and revoked records with sandbox, host, status and expiry so you can audit what you issued. revoke asks for confirmation unless -y is used. Revocation prevents use on new connections immediately; a connection that already resolved the value can keep it until it closes. Deleting a secret is not a substitute for inspecting and revoking its grants, and deleting a plain env secret does not pull the copy already in a guest back out.

  • netd intercepts outbound TLS on port 443 for a granted host and substitutes placeholders in HTTP/1.1 request header values only. It verifies the upstream host’s TLS certificate. It rejects placeholders in the URL, Host header or request body. This does not cover HTTP, gRPC/h2-only traffic, or arbitrary TCP protocols.
  • A grant restricts where a credential can be resolved; it does not stop guest code from making authorized requests to that host. A malicious agent could spend its grant until it expires or is revoked. Use a narrow API key, host list, egress policy and TTL.
  • Plain create --secret NAME is different: it puts the real value in the guest environment. Any guest code can read it, and memory snapshots can retain it. Choose that only when you trust the guest with the value.
  • v2.4+ guest agent support is necessary for the grant’s per-sandbox CA. A sandbox created before v2.4 retains its old agent even after a server upgrade; recreate it if grant/fork requests say the agent is outdated. An existing sandbox created without a network or from a filesystem-only snapshot may also lack the substitution CA and needs recreation.

See Secrets management for encryption/ownership and Networking internals for what netd does with a request.