Polski
Menu dokumentacji

Dokumentacja Agent Sandboxes · Zadania

Sekrety i ruch wychodzący: klucze, których sandbox nie trzyma

Zaktualizowano · 7 min czytania

Sandbox uruchamia kod, któremu możesz nie ufać: agenta, użytkownika, pakietu. Dwa ustawienia trzymają go w ryzach. Sekret to klucz, którego sandbox nigdy nie trzyma: widzi znacznik, a proxy ruchu wychodzącego wstawia prawdziwy klucz do ruchu, tylko do wskazanych przez ciebie hostów. Ruch wychodzący to lista miejsc, z którymi sandbox w ogóle może się łączyć.

W skrócie
  • SetSecret trzyma wartość w przestrzeni roboczej razem z jej hostami; zmienna z nim powiązana (EnvVar.secret) trzyma znacznik, phs_….
  • Podmiana: tylko w nagłówkach żądań HTTPS do hostów sekretu, tak samo w Authorization, jak i x-api-key. Nowa wartość działa od razu.
  • egress.allow i deny: domeny, subdomeny, IP i CIDR, z portem, gdy to nie 80 i 443; deny wygrywa; domyślnie wszędzie.
  • Wychodzą tylko TCP i DNS, a DNS sandboxa odpowiada tylko na nazwy, które dopuszcza lista.

Step 1: Zapisz sekret z jego hostami

Sekret ma nazwę (a-z, 0-9 i „-”), wartość i hosty, do których wolno wysłać wartość. Ustawiaj go z własnego środowiska, nigdy z promptu ani z pliku w sandboxie. Ponowne ustawienie zastępuje jednocześnie wartość i hosty.

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: Utwórz sandbox, który go wiąże, za listą dozwolonych

Powiąż zmienną z sekretem w environment sandboxa i wypisz w egress.allow, dokąd może się łączyć: tutaj indeks pakietów Pythona i host sekretu. Ruch wychodzący musi dopuszczać hosty sekretu.

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: Zobacz, co widzi sandbox

W środku zmienna trzyma znacznik, żądanie do hosta sekretu niesie klucz, a nazwa, której lista nie dopuszcza, nawet się nie rozwiązuje.

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

Przebieg powyżej zapisał zmyślony klucz, na który OpenAI odpowiedziało 401; twój prawdziwy klucz dostanie 200. Tak czy inaczej żądanie opuściło sandbox z zapisaną wartością w miejscu znacznika.

Step 4: Zmieniaj listę w trakcie działania

UpdateSandbox z grupą egress zastępuje od razu całą listę i zamyka połączenia, których już nie dopuszcza. Nowa wartość sekretu nie wymaga niczego: wywołaj ponownie SetSecret, a każdy sandbox, który go wiąże, wyśle nową wartość od następnego żądania.

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

Jak działa sekret

Wartość sekretu jest w panelu, zaszyfrowana, i w pamięci serwerów, na których działają sandboxy, które go wiążą: nigdy na dysku sandboxa, nigdy w jego pamięci, nigdy w odpowiedzi API. Zmienna z nim powiązana trzyma znacznik zaczynający się od phs_, taki sam dla każdego procesu sandboxa.

Proxy ruchu wychodzącego sandboxa kończy TLS tylko dla hostów sekretu, certyfikatem urzędu certyfikacji samego serwera, któremu sandbox ufa: Node, Python, curl i git są na niego ustawione. W każdym żądaniu do tych hostów zamienia znacznik na wartość wszędzie, gdzie pojawia się w wartości nagłówka: Authorization: Bearer, x-api-key, wewnątrz danych Authorization: Basic. Żądanie do każdego innego hosta niesie znacznik, który nic tam nie jest wart. Podmiana działa tylko w nagłówkach, nie w treści żądania.

  • Hosty zapisuje się tak, jak ruch wychodzący zapisuje domeny: api.openai.com albo *.example.com dla subdomen, z portem, gdy to nie 443.
  • Nowa wartość działa od razu, w każdym działającym sandboxie i forku, który wiąże sekret.
  • Powiązanego sekretu nie da się usunąć: DeleteSecret jest odrzucane, dopóki wiąże go jakiś nieusunięty sandbox.
  • Przestrzeń robocza trzyma 100 sekretów. GetWorkspace wymienia ich nazwy i hosty, nigdy wartości.

Zdarzenia ruchu wychodzącego mówią, dla każdego hosta i minuty, które sekrety podstawiono w jego żądaniach: obserwowalność.

Jak działa ruch wychodzący

egress sandboxa ma dwie listy. allow mówi, dokąd może się łączyć, deny, dokąd nie może, a deny wygrywa. Domyślnie allow to ["*"], czyli wszędzie. Wysłana grupa zastępuje całą grupę: samo deny zostawia allow puste, więc żeby zablokować kilka hostów, wyślij razem z nimi allow ["*"]. Razem mieszczą 100 wpisów, każdy do 255 bajtów.

WpisOtwiera
*Wszędzie.
pypi.orgTę domenę, na portach 80 i 443.
*.github.comJej subdomeny na dowolnej głębokości, bez samego github.com.
github.com:22Tę domenę na tym porcie: git przez SSH.
203.0.113.7, 203.0.113.0/24Te adresy, wybierane po adresie, z :port, gdy to nie 80 i 443.
  • Z sandboxa wychodzą tylko TCP i DNS: bez UDP, więc bez QUIC i HTTP/3, i bez pinga, niezależnie od listy.
  • DNS odpowiada tylko na dozwolone nazwy. Resolver sandboxa odpowiada REFUSED na nazwę, której nie dopuszcza żaden wpis z domeną, nikogo nie pytając, więc żadne dane nie wychodzą przez zapytania DNS.
  • TLS ocenia się po nazwie, którą wysyła klient, a proxy łączy się z adresem, który rozwiązało samo, nigdy z tym, który wybrał sandbox. Wpis z domeną ufa wszystkiemu, co serwują adresy tej nazwy, łącznie z innymi stronami CDN: granica, która musi tam trzymać, wymienia IP albo wiąże sekret z hostem, którego żądania proxy czyta wtedy jedno po drugim.
  • Zwykłe HTTP ocenia się żądanie po żądaniu: żądanie do innego hosta niż host jego połączenia dostaje 421, a nowe połączenie klienta jest oceniane po tym hoście.
  • SSH i inne protokoły nie podają hosta i przechodzą tylko do wpisu z domeną, który podaje port, jak github.com:22.
  • Zawsze odrzucane: adresy prywatne, link-local i CGNAT, sam serwer, port 25 oraz HTTP/2 bez TLS.
  • Odmowa, na którą proxy może odpowiedzieć, to 403, które mówi, co odmówiło.

Każdy sandbox ma też własne granice: 200 nowych połączeń na sekundę po zapasie 1000, 1024 otwartych naraz i 200 zapytań DNS na sekundę.

Listy, które działają

Dlaallow
pip i uvpypi.org, files.pythonhosted.org
npmregistry.npmjs.org
git przez HTTPS i SSHgithub.com, *.githubusercontent.com, github.com:22
Claude Codeapi.anthropic.com
Codexapi.openai.com

Obserwuj zdarzenia ruchu wychodzącego sandboxa przez minutę prawdziwej pracy, żeby znaleźć, czego jeszcze potrzebuje: każde podaje host, czy go dopuszczono i ile bajtów poszło w każdą stronę.

Gdy to nie działa

  • „Could not resolve host”: żaden wpis nie dopuszcza tej nazwy. Dodaj ją do allow.
  • 403, które wskazuje politykę ruchu wychodzącego: host albo jego port nie są dopuszczone albo pasował wpis deny. SSH potrzebuje portu we wpisie.
  • Usługa odpowiada 401 mimo powiązanego sekretu: żądanie poszło do hosta, którego sekret nie wymienia, albo klient włożył klucz do treści, gdzie nie ma podmiany, albo przypina własne certyfikaty. Wpisz host w hosts sekretu i wysyłaj klucz w nagłówku.
  • INVALID_ARGUMENT przy utworzeniu albo zmianie: ruch wychodzący sandboxa nie dopuszcza hostów powiązanego sekretu albo sekret nie istnieje. Dopuść je albo najpierw ustaw sekret.
  • FAILED_PRECONDITION przy DeleteSecret: wiąże go jakiś sandbox. Odwiąż go przez UpdateSandbox albo usuń ten sandbox.
  • RESOURCE_EXHAUSTED z LimitReached, secrets: przestrzeń robocza ma 100 sekretów. Usuń któryś, którego już nie wiążesz.

Pytania

Czy proces w sandboxie może odczytać mój klucz API?

Nie. Powiązana zmienna trzyma znacznik; proxy ruchu wychodzącego, poza maszyną wirtualną, wstawia klucz do żądań do hostów sekretu.

Które żądania dostają prawdziwy klucz?

Żądania HTTPS do hostów wymienionych w sekrecie, w ich nagłówkach. Każdy inny host dostaje znacznik.

Jak odciąć sandboxowi dostęp do internetu?

Wyślij egress z pustym allow: nic nie wychodzi, a DNS niczego nie rozwiązuje. Dodaj tylko to, czego wymaga praca.

Czy sandbox ma UDP?

Nie. Z sandboxa wychodzą tylko TCP i DNS, więc QUIC, HTTP/3 i ping nie działają, niezależnie od listy.

Czy zmiany ruchu wychodzącego działają w działającym sandboxie?

Tak, od razu: połączenia, których nowa lista już nie dopuszcza, są zamykane.

Wypróbuj Pethost Agent Sandboxes

Okres próbny na 7 dni z 1 $ zużycia i 4 vCPU, z kartą. Potem plan od 20 $ miesięcznie, który zawiera tyle samo zużycia.

Zacznij okres próbny