Português
Menu da documentação

Docs do Agent Sandboxes · Tarefas

Segredos e saída: chaves que um sandbox nunca guarda

Atualizado em · 8 min de leitura

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.

Em resumo
  • SetSecret guarda 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, Authorization e x-api-key igualmente. Um novo valor funciona na hora.
  • egress.allow e deny: domínios, subdomínios, IPs e CIDRs, com uma porta quando não for 80 e 443; deny vence; 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.

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: 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.

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: 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.

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

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.

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

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.com para 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. GetWorkspace lista 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.

EntradaLibera
*Qualquer lugar.
pypi.orgEsse domínio, nas portas 80 e 443.
*.github.comOs subdomínios dele em qualquer nível, não o próprio github.com.
github.com:22Esse domínio nessa porta: git por SSH.
203.0.113.7, 203.0.113.0/24Esses 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

Paraallow
pip e uvpypi.org, files.pythonhosted.org
npmregistry.npmjs.org
git por HTTPS e SSHgithub.com, *.githubusercontent.com, github.com:22
Claude Codeapi.anthropic.com
Codexapi.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 deny bateu. 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 hosts do segredo e envie a chave em um cabeçalho.
  • INVALID_ARGUMENT em 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_PRECONDITION em DeleteSecret: um sandbox o liga. Desligue-o com UpdateSandbox, ou exclua esse sandbox.
  • RESOURCE_EXHAUSTED com LimitReached, 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.

Começar o teste grátis