Docs do Agent Sandboxes · Tarefas
Segredos e saída: chaves que um sandbox nunca guarda
Um sandbox roda código em que você talvez não confie: o de um agente, o de um usuário, o de um pacote. Duas configurações o mantêm nos limites. Um segredo é uma chave que o sandbox nunca guarda: ele vê um marcador, e o proxy de saída coloca a chave real na requisição, só para os hosts que você indicar. A saída é a lista dos lugares a que ele pode se conectar.
SetSecretguarda um valor no espaço de trabalho com os hosts dele; uma variável ligada a ele (EnvVar.secret) guarda um marcador,phs_….- A troca: nos cabeçalhos das requisições HTTPS só para os hosts do segredo,
Authorizationex-api-keyigualmente. Um novo valor funciona na hora. egress.allowedeny: domínios, subdomínios, IPs e CIDRs, com uma porta quando não for 80 e 443;denyvence; por padrão, qualquer lugar.- Só TCP e DNS saem, e o DNS do sandbox só responde nomes que a lista permite.
Step 1: Salve um segredo com os hosts dele
Um segredo tem um nome (a-z, 0-9 e “-”), um valor e os hosts para os quais o valor pode ser enviado. Defina-o a partir do seu próprio ambiente, nunca de um prompt ou de um arquivo no sandbox. Defini-lo de novo substitui o valor e os hosts juntos.
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: Crie um sandbox que o ligue, atrás de uma lista de permissões
Ligue uma variável ao segredo no environment do sandbox e liste em egress.allow aonde ele pode se conectar: aqui, o índice de pacotes do Python e o host do segredo. A saída precisa permitir os hosts do segredo.
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: Veja o que o sandbox vê
Lá dentro, a variável guarda o marcador, uma requisição para o host do segredo leva a chave, e um nome que a lista não permite nem chega a ser resolvido.
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);
A execução acima guardou uma chave inventada, a que a OpenAI respondeu 401; a sua chave real responde 200. De qualquer forma, a requisição saiu do sandbox com o valor guardado no lugar do marcador.
Step 4: Altere a lista com ele rodando
UpdateSandbox com um grupo egress substitui a lista inteira de uma vez e fecha as conexões que ela não permite mais. Um novo valor de um segredo não precisa de nada: SetSecret de novo, e todo sandbox que o liga envia o novo a partir da próxima requisição.
$ 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"]}}}
Como um segredo funciona
O valor de um segredo fica no painel, selado, e na memória dos servidores que rodam sandboxes que o ligam: nunca no disco de um sandbox, nunca na memória dele, nunca em uma resposta da API. Uma variável ligada a ele guarda um marcador que começa com phs_, o mesmo para todo processo do sandbox.
O proxy de saída do sandbox termina o TLS só para os hosts do segredo, com um certificado da autoridade do próprio servidor, em que o sandbox confia: Node, Python, curl e git são apontados para ela. Em cada requisição para esses hosts, ele troca o marcador pelo valor onde quer que ele apareça no valor de um cabeçalho: Authorization: Bearer, x-api-key, dentro das credenciais de Authorization: Basic. Uma requisição para qualquer outro host leva o marcador, que ali não vale nada. A troca é só nos cabeçalhos, não no corpo da requisição.
- Os hosts são escritos como a saída escreve domínios:
api.openai.com, ou*.example.compara os subdomínios dele, com uma porta quando não for 443. - Um novo valor funciona na hora, em todo sandbox rodando e em todo fork que liga o segredo.
- Um segredo ligado não pode ser excluído:
DeleteSecreté recusado enquanto um sandbox não excluído o liga. - Um espaço de trabalho guarda 100 segredos.
GetWorkspacelista os nomes e os hosts deles, nunca os valores.
Os eventos de saída dizem, para cada host e minuto, quais segredos foram trocados nas requisições dele: observabilidade.
Como a saída funciona
O egress de um sandbox tem duas listas. allow diz aonde ele pode se conectar, deny aonde não pode, e deny vence. Por padrão, allow é ["*"], qualquer lugar. Um grupo enviado substitui o grupo inteiro: deny enviado sozinho deixa allow vazio, então para bloquear alguns hosts envie allow ["*"] junto com eles. Juntas, elas comportam 100 entradas de no máximo 255 bytes.
| Entrada | Libera |
|---|---|
* | Qualquer lugar. |
pypi.org | Esse domínio, nas portas 80 e 443. |
*.github.com | Os subdomínios dele em qualquer nível, não o próprio github.com. |
github.com:22 | Esse domínio nessa porta: git por SSH. |
203.0.113.7, 203.0.113.0/24 | Esses endereços, acessados pelo endereço, com :port quando não for 80 e 443. |
- Só TCP e DNS saem de um sandbox: nada de UDP, portanto nada de QUIC ou HTTP/3, e nada de ping, diga a lista o que disser.
- O DNS só responde nomes permitidos. O resolvedor do sandbox responde REFUSED para um nome que nenhuma entrada de domínio permite, sem perguntar a ninguém, então nenhum dado sai por consultas DNS.
- O TLS é julgado pelo nome que o cliente envia, e o proxy se conecta ao endereço que ele mesmo resolveu, nunca ao que o sandbox escolheu. Uma entrada de domínio confia em tudo o que os endereços desse nome servem, incluindo os outros sites de uma CDN: uma barreira que precisa valer ali nomeia IPs, ou liga um segredo ao host, cujas requisições o proxy então lê uma a uma.
- HTTP puro é julgado requisição por requisição: uma requisição para um host diferente do da conexão recebe 421, e a nova conexão do cliente é julgada por esse host.
- SSH e outros protocolos não nomeiam host e só passam para uma entrada de domínio que nomeia a porta, como
github.com:22. - Sempre recusados: endereços privados, link-local e CGNAT, o próprio servidor, a porta 25 e HTTP/2 sem TLS.
- Uma recusa que o proxy consegue responder é um 403 que diz o que a recusou.
Cada sandbox também tem limites próprios: 200 novas conexões por segundo depois de um pico de 1.000, 1.024 abertas ao mesmo tempo e 200 consultas DNS por segundo.
Listas que funcionam
| Para | allow |
|---|---|
| pip e uv | pypi.org, files.pythonhosted.org |
| npm | registry.npmjs.org |
| git por HTTPS e SSH | github.com, *.githubusercontent.com, github.com:22 |
| Claude Code | api.anthropic.com |
| Codex | api.openai.com |
Acompanhe os eventos de saída de um sandbox durante um minuto de trabalho real para descobrir do que mais ele precisa: cada um diz o host, se ele foi permitido e quantos bytes passaram em cada sentido.
Quando não funciona
- “Could not resolve host”: nenhuma entrada permite esse nome. Adicione-o a
allow. - Um 403 que nomeia a política de saída: o host, ou a porta dele, não é permitido, ou uma entrada de
denybateu. O SSH precisa da porta na entrada. - O serviço responde 401 com um segredo ligado: a requisição foi para um host que o segredo não nomeia, ou o cliente colocou a chave no corpo, onde nenhuma troca é feita, ou fixa os próprios certificados. Nomeie o host nos
hostsdo segredo e envie a chave em um cabeçalho. INVALID_ARGUMENTem uma criação ou alteração: os hosts de um segredo ligado não são permitidos pela saída do sandbox, ou o segredo não existe. Permita-os, ou defina o segredo antes.FAILED_PRECONDITIONemDeleteSecret: um sandbox o liga. Desligue-o comUpdateSandbox, ou exclua esse sandbox.RESOURCE_EXHAUSTEDcomLimitReached,secrets: o espaço de trabalho tem 100. Exclua um que você não liga mais.
Perguntas
Um processo no sandbox consegue ler a minha chave de API?
Não. Uma variável ligada guarda um marcador; o proxy de saída, fora da VM, coloca a chave nas requisições para os hosts do segredo.
Quais requisições recebem a chave real?
Requisições HTTPS para os hosts que o segredo nomeia, nos cabeçalhos. Todo outro host recebe o marcador.
Como bloqueio o acesso à internet em um sandbox?
Envie egress com um allow vazio: nada sai, e o DNS não resolve nada. Adicione só o que o trabalho precisa.
Um sandbox tem UDP?
Não. Só TCP e DNS saem de um sandbox, então QUIC, HTTP/3 e ping não funcionam, diga a lista o que disser.
Mudanças na saída valem para um sandbox rodando?
Sim, na hora: conexões que a nova lista não permite mais são fechadas.
Experimente o Pethost Agent Sandboxes
Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.