---
title: "Secrets and egress: keys a sandbox never holds | Pethost Agent Sandboxes"
description: "Give a sandbox API keys it never holds, swapped in by the egress proxy for the hosts you name, and limit where it may connect with an allow-list."
---

[Agent Sandboxes docs](https://pethost.dev/docs/sandboxes/) · Tasks

# Secrets and egress: keys a sandbox never holds

Updated 22 November 2026 · 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](https://pethost.dev/docs/sandboxes/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.

| Entry | Opens |
| --- | --- |
| `*` | Anywhere. |
| `pypi.org` | That domain, on ports 80 and 443. |
| `*.github.com` | Its subdomains at any depth, not `github.com` itself. |
| `github.com:22` | That domain on that port: git over SSH. |
| `203.0.113.7`, `203.0.113.0/24` | Those 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

| For | `allow` |
| --- | --- |
| pip and uv | `pypi.org`, `files.pythonhosted.org` |
| npm | `registry.npmjs.org` |
| git over HTTPS and SSH | `github.com`, `*.githubusercontent.com`, `github.com:22` |
| Claude Code | `api.anthropic.com` |
| Codex | `api.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.

[PreviousTemplates: start sandboxes ready to work](https://pethost.dev/docs/sandboxes/templates/) [NextFork a sandbox, memory and processes included](https://pethost.dev/docs/sandboxes/forks/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/templates/)
- [About](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Terms](https://pethost.dev/terms/)
- [Privacy](https://pethost.dev/privacy/)
- [Refunds](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Databases

- [Postgres](https://pethost.dev/postgres/)
- [Valkey](https://pethost.dev/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/sandboxes/)
- [Pricing](https://pethost.dev/sandboxes/#pricing)
- [Docs](https://pethost.dev/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparisons

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/blog/coolify-cloud-vs-dokploy-cloud/)
- [Railway vs Render vs Fly.io pricing](https://pethost.dev/blog/railway-vs-render-vs-fly-io-pricing/)
- [Managed Docker Compose hosting](https://pethost.dev/blog/managed-docker-compose-hosting/)

Alternatives

- [Railway alternatives](https://pethost.dev/blog/railway-alternatives/)
- [Heroku alternatives](https://pethost.dev/blog/heroku-alternatives/)
- [Dokploy alternatives](https://pethost.dev/blog/dokploy-alternatives/)
- [Coolify alternatives](https://pethost.dev/blog/coolify-alternatives/)
- [Render alternatives](https://pethost.dev/blog/render-alternatives/)
- [Sliplane alternatives](https://pethost.dev/blog/sliplane-alternatives/)
