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.
Grant while creating the sandbox
Section titled “Grant while creating the sandbox”bhatti secret set MODEL_KEY 'real-value'bhatti create --name model-agent \ --allow-host api.openai.com \ --secret-grant MODEL_KEY@api.openai.comThe guest’s MODEL_KEY environment variable contains a placeholder, not the secret. Pass it as you would an ordinary token in a request header:
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.
Grant to an existing sandbox
Section titled “Grant to an existing sandbox”bhatti create --name github-agent --allow-host api.github.combhatti secret set GH_TOKEN 'real-value'bhatti secret grant GH_TOKEN --sandbox github-agent --host api.github.com --ttl 7dsecret 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.
List and revoke
Section titled “List and revoke”bhatti secret grantsbhatti secret revoke <grant-id># In non-interactive automation:bhatti secret revoke <grant-id> -ygrants 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.
Where the boundary ends
Section titled “Where the boundary ends”- 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 NAMEis 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.