English
Docs menu

Agent Sandboxes docs · Tasks

Secrets and egress: keys a sandbox never holds

Updated · 8 min read

A sandbox runs code you may not trust: an agent's, a user's, a package's. Two settings keep it in bounds. A secret is a key the sandbox never holds: it sees a placeholder, and the egress proxy puts the real key on the wire, only to the hosts you name. Egress is the list of where it may connect at all.

In short
  • SetSecret keeps a value in the workspace with its hosts; a variable bound to it (EnvVar.secret) holds a placeholder, phs_….
  • The swap: in the headers of HTTPS requests to the secret's hosts alone, Authorization and x-api-key alike. A new value works at once.
  • egress.allow and deny: domains, subdomains, IPs and CIDRs, a port where it is not 80 and 443; deny wins; by default, anywhere.
  • Only TCP and DNS leave, and the sandbox's DNS answers only names the list allows.

Step 1: Save a secret with its hosts

A secret has a name (a-z, 0-9 and "-"), a value and the hosts the value may be sent to. Set it from your own environment, never from a prompt or a file in the sandbox. Setting it again replaces its value and hosts together.

Python
import os

sandboxes.set_secret("openai", value=os.environ["OPENAI_API_KEY"], hosts=["api.openai.com"])
TypeScript
await sandboxes.setSecret({ name: "openai", value: process.env.OPENAI_API_KEY!, hosts: ["api.openai.com"] });
Go
_, err = client.SetSecret(ctx, &sandboxes.SetSecretRequest{
	Name:  "openai",
	Value: os.Getenv("OPENAI_API_KEY"),
	Hosts: []string{"api.openai.com"},
})
Rust
sandboxes
    .set_secret(SetSecretRequest {
        name: "openai".into(),
        value: std::env::var("OPENAI_API_KEY")?,
        hosts: vec!["api.openai.com".into()],
        ..Default::default()
    })
    .await?;
CLI
$ printf %s "$OPENAI_API_KEY" | pethost sandbox secret set openai --host api.openai.com
✓ Set the secret openai for api.openai.com. Bind it:  --env <VARIABLE>=secret:openai
openai

Step 2: Make a sandbox that binds it, behind an allow-list

Bind a variable to the secret in the sandbox's environment, and list in egress.allow where it may connect: here the Python package index and the secret's host. The egress must allow the secret's hosts.

Python
from pethost.sandboxes import Egress, Environment, EnvVar, SandboxSettings

sandbox = sandboxes.create_sandbox("base", settings=SandboxSettings(
    environment=Environment(variables=[EnvVar(name="OPENAI_API_KEY", secret="openai")]),
    egress=Egress(allow=["pypi.org", "files.pythonhosted.org", "api.openai.com"]),
))
sandbox_id = sandbox.sandbox_id
TypeScript
const sandbox = await sandboxes.createSandbox({
  template: "base",
  settings: {
    environment: { variables: [{ name: "OPENAI_API_KEY", secret: "openai" }] },
    egress: { allow: ["pypi.org", "files.pythonhosted.org", "api.openai.com"] },
  },
});
const sandboxId = sandbox.sandboxId;
Go
sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "base", Settings: &sandboxes.SandboxSettings{
	Environment: &sandboxes.Environment{Variables: []sandboxes.EnvVar{
		{Name: "OPENAI_API_KEY", Source: sandboxes.EnvVarSecret("openai")},
	}},
	Egress: &sandboxes.Egress{Allow: []string{"pypi.org", "files.pythonhosted.org", "api.openai.com"}},
}})
if err != nil {
	log.Fatal(err)
}
id := sandbox.SandboxID
Rust
let key = EnvVar { name: "OPENAI_API_KEY".into(), source: Some(EnvVarSource::Secret("openai".into())) };
let allow = ["pypi.org", "files.pythonhosted.org", "api.openai.com"].map(String::from).to_vec();
let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        template: "base".into(),
        settings: Some(SandboxSettings {
            environment: Some(Environment { variables: vec![key] }),
            egress: Some(Egress { allow, ..Default::default() }),
            ..Default::default()
        }),
        ..Default::default()
    })
    .await?;
let id = sandbox.sandbox_id.clone();
CLI
$ pethost sandbox new --name fenced --env OPENAI_API_KEY=secret:openai \
    --allow pypi.org --allow files.pythonhosted.org --allow api.openai.com
✓ Made sandbox fenced (xhww8xdrh7jj2d8c): default, running, from base@17, in <1 s
xhww8xdrh7jj2d8c
Next:   pethost sandbox run xhww8xdrh7jj2d8c -- <command>   ·   pethost sandbox shell xhww8xdrh7jj2d8c
MCP
CreateSandbox {"name": "fenced", "settings": {"environment": {"variables": [{"name": "OPENAI_API_KEY", "secret": "openai"}]}, "egress": {"allow": ["pypi.org", "files.pythonhosted.org", "api.openai.com"]}}}

Step 3: See what the sandbox sees

Inside, the variable holds the placeholder, a request to the secret's host carries the key, and a name the list does not allow does not even resolve.

Python
check = sandboxes.run_command(sandbox_id, command=(
    'echo "$OPENAI_API_KEY" | cut -c1-8; '
    'curl -s -o /dev/null -w "%{http_code}\\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; '
    'curl -sS https://example.com'
))
print(check.stdout, check.stderr)
# phs_szjl
# 401
#  curl: (6) Could not resolve host: example.com
TypeScript
const check = await sandboxes.runCommand({
  sandboxId,
  command:
    'echo "$OPENAI_API_KEY" | cut -c1-8; ' +
    'curl -s -o /dev/null -w "%{http_code}\\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; ' +
    "curl -sS https://example.com",
});
console.log(check.stdout, check.stderr);
Go
check, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: id, Command: `echo "$OPENAI_API_KEY" | cut -c1-8; ` +
	`curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; ` +
	`curl -sS https://example.com`})
if err != nil {
	log.Fatal(err)
}
fmt.Println(check.Stdout, check.Stderr)
Rust
let check = sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: id.clone(),
        command: concat!(
            r#"echo "$OPENAI_API_KEY" | cut -c1-8; "#,
            r#"curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; "#,
            "curl -sS https://example.com",
        )
        .into(),
        ..Default::default()
    })
    .await?;
println!("{} {}", check.stdout, check.stderr);

The run above stored a made-up key, which OpenAI answered with 401; your real key answers 200. Either way the request left the sandbox with the stored value in place of the placeholder.

Step 4: Change the list while it runs

UpdateSandbox with an egress group replaces the whole list at once, and closes the connections it no longer allows. A new value of a secret needs nothing: SetSecret again, and every sandbox that binds it sends the new one from its next request.

CLI
$ pethost sandbox set fenced --allow pypi.org --allow files.pythonhosted.org --allow api.openai.com --allow github.com:22
MCP
UpdateSandbox {"sandbox_id": "…", "settings": {"egress": {"allow": ["pypi.org", "files.pythonhosted.org", "api.openai.com", "github.com:22"]}}}

How a secret works

A secret's value lives in the panel, sealed, and in the memory of the servers that run sandboxes binding it: never on a sandbox's disk, never in its memory, never in an answer of the API. A variable bound to it holds a placeholder that starts with phs_, the same for every process of the sandbox.

The sandbox's egress proxy terminates TLS for the secret's hosts alone, with a certificate of the server's own authority, which the sandbox trusts: Node, Python, curl and git are pointed at it. In each request to those hosts it swaps the placeholder for the value wherever it appears in a header's value: Authorization: Bearer, x-api-key, inside the credentials of Authorization: Basic. A request to any other host carries the placeholder, which is worth nothing there. The swap is in headers only, not in a request's body.

  • Hosts are written as egress writes domains: api.openai.com, or *.example.com for its subdomains, with a port where it is not 443.
  • A new value works at once, in every running sandbox and fork that binds the secret.
  • A bound secret cannot be deleted: DeleteSecret is refused while a sandbox that is not deleted binds it.
  • A workspace holds 100 secrets. GetWorkspace lists their names and hosts, never their values.

The egress events say, for each host and minute, which secrets were swapped into its requests: observability.

How egress works

A sandbox's egress has two lists. allow says where it may connect, deny where it may not, and deny wins. By default allow is ["*"], anywhere. A group sent replaces the whole group: deny sent alone leaves allow empty, so to block a few hosts send allow ["*"] with them. Together they hold 100 entries of 255 bytes at most.

EntryOpens
*Anywhere.
pypi.orgThat domain, on ports 80 and 443.
*.github.comIts subdomains at any depth, not github.com itself.
github.com:22That domain on that port: git over SSH.
203.0.113.7, 203.0.113.0/24Those addresses, dialed by address, with :port where it is not 80 and 443.
  • Only TCP and DNS leave a sandbox: no UDP, so no QUIC or HTTP/3, and no ping, whatever the list says.
  • DNS answers only allowed names. The sandbox's resolver answers REFUSED for a name no domain entry allows, without asking anyone, so no data leaves through DNS questions.
  • TLS is judged by the name the client sends, and the proxy dials the address it resolved itself, never the one the sandbox chose. A domain entry trusts whatever that name's addresses serve, a CDN's other sites included: a fence that must hold there names IPs, or binds a secret to the host, whose requests the proxy then reads one by one.
  • Plain HTTP is judged request by request: a request for another host than its connection's is answered 421, and the client's new connection is judged by that host.
  • SSH and other protocols name no host, and pass only to a domain entry that names the port, as github.com:22.
  • Always refused: private, link-local and CGNAT addresses, the server itself, port 25, and HTTP/2 without TLS.
  • A refusal the proxy can answer is a 403 that says what refused it.

Each sandbox also has bounds of its own: 200 new connections a second after a burst of 1,000, 1,024 open at once, and 200 DNS questions a second.

Lists that work

Forallow
pip and uvpypi.org, files.pythonhosted.org
npmregistry.npmjs.org
git over HTTPS and SSHgithub.com, *.githubusercontent.com, github.com:22
Claude Codeapi.anthropic.com
Codexapi.openai.com

Watch a sandbox's egress events for a minute of real work to find what else it needs: each says the host, whether it was allowed and how many bytes went each way.

When it does not work

  • “Could not resolve host”: no entry allows that name. Add it to allow.
  • A 403 that names the egress policy: the host, or its port, is not allowed, or a deny entry matched. SSH needs the port in its entry.
  • The service answers 401 with a bound secret: the request went to a host the secret does not name, or the client put the key in the body, where no swap is made, or pins its own certificates. Name the host in the secret's hosts, and send the key in a header.
  • INVALID_ARGUMENT on a create or an update: a bound secret's hosts are not allowed by the sandbox's egress, or the secret does not exist. Allow them, or set the secret first.
  • FAILED_PRECONDITION on DeleteSecret: a sandbox binds it. Unbind it with UpdateSandbox, or delete that sandbox.
  • RESOURCE_EXHAUSTED with LimitReached, secrets: the workspace has 100. Delete one you no longer bind.

Questions

Can a process in the sandbox read my API key?

No. A bound variable holds a placeholder; the egress proxy, outside the VM, puts the key into requests to the secret's hosts.

Which requests get the real key?

HTTPS requests to the hosts the secret names, in their headers. Every other host gets the placeholder.

How do I block internet access in a sandbox?

Send egress with an empty allow: nothing leaves, and DNS resolves nothing. Add only what the work needs.

Does a sandbox have UDP?

No. Only TCP and DNS leave a sandbox, so QUIC, HTTP/3 and ping do not work, whatever the list says.

Do egress changes apply to a running sandbox?

Yes, at once: connections the new list no longer allows are closed.

Try Pethost Agent Sandboxes

A 7-day trial with $1 of usage and 4 vCPUs, with a card. Then a plan from $20 a month, which includes as much usage.

Start the trial