Deutsch
Menü der Doku

Doku zu Agent Sandboxes · Aufgaben

Secrets und Egress: Keys, die eine Sandbox nie hält

Aktualisiert · 8 Min. Lesezeit

Eine Sandbox führt Code aus, dem du vielleicht nicht vertraust: den eines Agenten, eines Nutzers, eines Pakets. Zwei Einstellungen halten ihn in Grenzen. Ein Secret ist ein Key, den die Sandbox nie hält: Sie sieht einen Platzhalter, und der Egress-Proxy schickt den echten Key, nur an die Hosts, die du nennst. Egress ist die Liste, wohin sie sich überhaupt verbinden darf.

Kurz gesagt
  • SetSecret hält einen Wert mit seinen Hosts im Workspace; eine daran gebundene Variable (EnvVar.secret) hält einen Platzhalter, phs_….
  • Der Tausch: nur in den Headern von HTTPS-Requests an die Hosts des Secrets, Authorization wie x-api-key. Ein neuer Wert gilt sofort.
  • egress.allow und deny: Domains, Subdomains, IPs und CIDRs, ein Port, wo er nicht 80 und 443 ist; deny gewinnt; standardmäßig überallhin.
  • Nur TCP und DNS gehen hinaus, und das DNS der Sandbox beantwortet nur Namen, die die Liste erlaubt.

Step 1: Secret mit seinen Hosts speichern

Ein Secret hat einen Namen (a-z, 0-9 und „-“), einen Wert und die Hosts, an die der Wert geschickt werden darf. Setz es aus deiner eigenen Umgebung, nie aus einem Prompt oder einer Datei in der Sandbox. Es erneut zu setzen ersetzt Wert und Hosts zusammen.

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: Sandbox erstellen, die es bindet, hinter einer Allowlist

Binde in der environment der Sandbox eine Variable an das Secret, und liste in egress.allow, wohin sie sich verbinden darf: hier den Python-Paketindex und den Host des Secrets. Der Egress muss die Hosts des Secrets erlauben.

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: Sehen, was die Sandbox sieht

Darin hält die Variable den Platzhalter, ein Request an den Host des Secrets trägt den Key, und ein Name, den die Liste nicht erlaubt, löst nicht einmal auf.

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);

Der Lauf oben hat einen erfundenen Key gespeichert, den OpenAI mit 401 beantwortet hat; dein echter Key antwortet 200. So oder so hat der Request die Sandbox mit dem gespeicherten Wert anstelle des Platzhalters verlassen.

Step 4: Liste ändern, während sie läuft

UpdateSandbox mit einer egress-Gruppe ersetzt die ganze Liste auf einmal und schließt die Verbindungen, die sie nicht mehr erlaubt. Ein neuer Wert eines Secrets braucht nichts: SetSecret noch einmal, und jede Sandbox, die es bindet, schickt ab ihrem nächsten Request den neuen.

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"]}}}

Wie ein Secret funktioniert

Der Wert eines Secrets liegt versiegelt im Panel und im RAM der Server, die Sandboxes ausführen, die es binden: nie auf der Disk einer Sandbox, nie in ihrem RAM, nie in einer Antwort der API. Eine daran gebundene Variable hält einen Platzhalter, der mit phs_ beginnt, für jeden Prozess der Sandbox derselbe.

Der Egress-Proxy der Sandbox terminiert TLS nur für die Hosts des Secrets, mit einem Zertifikat der eigenen Zertifizierungsstelle des Servers, der die Sandbox vertraut: Node, Python, curl und git sind auf sie eingestellt. In jedem Request an diese Hosts tauscht er den Platzhalter gegen den Wert, wo immer er im Wert eines Headers steht: Authorization: Bearer, x-api-key, in den Zugangsdaten von Authorization: Basic. Ein Request an jeden anderen Host trägt den Platzhalter, der dort nichts wert ist. Der Tausch geschieht nur in Headern, nicht im Body eines Requests.

  • Hosts werden geschrieben, wie Egress Domains schreibt: api.openai.com, oder *.example.com für seine Subdomains, mit einem Port, wo er nicht 443 ist.
  • Ein neuer Wert gilt sofort, in jeder laufenden Sandbox und jedem Fork, die das Secret binden.
  • Ein gebundenes Secret lässt sich nicht löschen: DeleteSecret wird abgelehnt, solange eine nicht gelöschte Sandbox es bindet.
  • Ein Workspace hält 100 Secrets. GetWorkspace listet ihre Namen und Hosts, nie ihre Werte.

Die Egress-Events sagen für jeden Host und jede Minute, welche Secrets in seine Requests eingesetzt wurden: Observability.

Wie Egress funktioniert

Der egress einer Sandbox hat zwei Listen. allow sagt, wohin sie sich verbinden darf, deny, wohin nicht, und deny gewinnt. Standardmäßig ist allow ["*"], überallhin. Eine geschickte Gruppe ersetzt die ganze Gruppe: deny allein geschickt lässt allow leer, also schick, um ein paar Hosts zu sperren, allow ["*"] mit ihnen. Zusammen halten sie 100 Einträge von höchstens 255 Bytes.

EintragÖffnet
*Überallhin.
pypi.orgDiese Domain, auf den Ports 80 und 443.
*.github.comDie Subdomains in jeder Tiefe, nicht github.com selbst.
github.com:22Diese Domain auf diesem Port: git über SSH.
203.0.113.7, 203.0.113.0/24Diese Adressen, über die Adresse angewählt, mit :port, wo er nicht 80 und 443 ist.
  • Nur TCP und DNS verlassen eine Sandbox: kein UDP, also kein QUIC oder HTTP/3, und kein Ping, egal, was die Liste sagt.
  • DNS beantwortet nur erlaubte Namen. Der Resolver der Sandbox antwortet REFUSED für einen Namen, den kein Domain-Eintrag erlaubt, ohne jemanden zu fragen, also verlassen keine Daten die Sandbox über DNS-Fragen.
  • TLS wird nach dem Namen beurteilt, den der Client schickt, und der Proxy wählt die Adresse an, die er selbst aufgelöst hat, nie die, die die Sandbox gewählt hat. Ein Domain-Eintrag vertraut allem, was die Adressen dieses Namens ausliefern, andere Sites eines CDN eingeschlossen: Ein Zaun, der dort halten muss, nennt IPs oder bindet ein Secret an den Host, dessen Requests der Proxy dann einzeln liest.
  • Einfaches HTTP wird Request für Request beurteilt: Ein Request für einen anderen Host als den seiner Verbindung bekommt 421, und die neue Verbindung des Clients wird nach diesem Host beurteilt.
  • SSH und andere Protokolle nennen keinen Host und gehen nur zu einem Domain-Eintrag durch, der den Port nennt, etwa github.com:22.
  • Immer abgelehnt: private, Link-Local- und CGNAT-Adressen, der Server selbst, Port 25 und HTTP/2 ohne TLS.
  • Eine Ablehnung, die der Proxy beantworten kann, ist ein 403, das sagt, was abgelehnt hat.

Jede Sandbox hat auch eigene Grenzen: 200 neue Verbindungen pro Sekunde nach einem Burst von 1.000, 1.024 gleichzeitig offen und 200 DNS-Fragen pro Sekunde.

Listen, die funktionieren

Fürallow
pip und uvpypi.org, files.pythonhosted.org
npmregistry.npmjs.org
git über HTTPS und SSHgithub.com, *.githubusercontent.com, github.com:22
Claude Codeapi.anthropic.com
Codexapi.openai.com

Beobachte die Egress-Events einer Sandbox eine Minute echter Arbeit lang, um herauszufinden, was sie noch braucht: Jedes nennt den Host, ob er erlaubt war und wie viele Bytes in jede Richtung gingen.

Wenn es nicht funktioniert

  • „Could not resolve host“: Kein Eintrag erlaubt diesen Namen. Füg ihn zu allow hinzu.
  • Ein 403, das die Egress-Richtlinie nennt: Der Host oder sein Port ist nicht erlaubt, oder ein deny-Eintrag hat gegriffen. SSH braucht den Port in seinem Eintrag.
  • Der Dienst antwortet 401 trotz gebundenem Secret: Der Request ging an einen Host, den das Secret nicht nennt, oder der Client hat den Key in den Body gelegt, wo nicht getauscht wird, oder pinnt eigene Zertifikate. Nenn den Host in den hosts des Secrets, und schick den Key in einem Header.
  • INVALID_ARGUMENT beim Erstellen oder Ändern: Der Egress der Sandbox erlaubt die Hosts eines gebundenen Secrets nicht, oder das Secret existiert nicht. Erlaube sie, oder setz das Secret zuerst.
  • FAILED_PRECONDITION bei DeleteSecret: Eine Sandbox bindet es. Löse die Bindung mit UpdateSandbox, oder lösch diese Sandbox.
  • RESOURCE_EXHAUSTED mit LimitReached, secrets: Der Workspace hat 100. Lösch eins, das du nicht mehr bindest.

Fragen

Kann ein Prozess in der Sandbox meinen API-Key lesen?

Nein. Eine gebundene Variable hält einen Platzhalter; der Egress-Proxy, außerhalb der VM, setzt den Key in Requests an die Hosts des Secrets ein.

Welche Requests bekommen den echten Key?

HTTPS-Requests an die Hosts, die das Secret nennt, in ihren Headern. Jeder andere Host bekommt den Platzhalter.

Wie sperre ich den Internetzugang einer Sandbox?

Schick egress mit leerem allow: Nichts geht hinaus, und DNS löst nichts auf. Füg nur hinzu, was die Arbeit braucht.

Hat eine Sandbox UDP?

Nein. Nur TCP und DNS verlassen eine Sandbox, also funktionieren QUIC, HTTP/3 und Ping nicht, egal, was die Liste sagt.

Gelten Änderungen am Egress für eine laufende Sandbox?

Ja, sofort: Verbindungen, die die neue Liste nicht mehr erlaubt, werden geschlossen.

Pethost Agent Sandboxes ausprobieren

Eine Testphase von 7 Tagen mit 1 $ Verbrauch und 4 vCPUs, mit Karte. Danach ein Tarif ab 20 $ im Monat, der genauso viel Verbrauch enthält.

Testphase starten