Dokumentacja Agent Sandboxes · Zadania
Sekrety i ruch wychodzący: klucze, których sandbox nie trzyma
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ć.
SetSecrettrzyma 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 ix-api-key. Nowa wartość działa od razu. egress.allowideny: domeny, subdomeny, IP i CIDR, z portem, gdy to nie 80 i 443;denywygrywa; 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.
import os
sandboxes.set_secret("openai", value=os.environ["OPENAI_API_KEY"], hosts=["api.openai.com"])
await sandboxes.setSecret({ name: "openai", value: process.env.OPENAI_API_KEY!, hosts: ["api.openai.com"] });
_, err = client.SetSecret(ctx, &sandboxes.SetSecretRequest{
Name: "openai",
Value: os.Getenv("OPENAI_API_KEY"),
Hosts: []string{"api.openai.com"},
})
sandboxes
.set_secret(SetSecretRequest {
name: "openai".into(),
value: std::env::var("OPENAI_API_KEY")?,
hosts: vec!["api.openai.com".into()],
..Default::default()
})
.await?;
$ 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.
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
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;
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
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();
$ 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
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.
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
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);
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)
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.
$ pethost sandbox set fenced --allow pypi.org --allow files.pythonhosted.org --allow api.openai.com --allow github.com:22
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.comalbo*.example.comdla 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ąć:
DeleteSecretjest odrzucane, dopóki wiąże go jakiś nieusunięty sandbox. - Przestrzeń robocza trzyma 100 sekretów.
GetWorkspacewymienia 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.
| Wpis | Otwiera |
|---|---|
* | Wszędzie. |
pypi.org | Tę domenę, na portach 80 i 443. |
*.github.com | Jej subdomeny na dowolnej głębokości, bez samego github.com. |
github.com:22 | Tę domenę na tym porcie: git przez SSH. |
203.0.113.7, 203.0.113.0/24 | Te 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ą
| Dla | allow |
|---|---|
| pip i uv | pypi.org, files.pythonhosted.org |
| npm | registry.npmjs.org |
| git przez HTTPS i SSH | github.com, *.githubusercontent.com, github.com:22 |
| Claude Code | api.anthropic.com |
| Codex | api.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
hostssekretu i wysyłaj klucz w nagłówku. INVALID_ARGUMENTprzy 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_PRECONDITIONprzyDeleteSecret: wiąże go jakiś sandbox. Odwiąż go przezUpdateSandboxalbo usuń ten sandbox.RESOURCE_EXHAUSTEDzLimitReached,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.