---
title: "Segredos e saída: chaves que um sandbox nunca guarda | Pethost Agent Sandboxes"
description: "Dê a um sandbox chaves de API que ele nunca guarda, trocadas pelo proxy de saída para os hosts indicados, e limite as conexões com uma lista de permissões."
---

[Docs do Agent Sandboxes](https://pethost.dev/pt/docs/sandboxes/) · Tarefas

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

Atualizado em 22 de novembro de 2026 · 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](https://pethost.dev/pt/docs/sandboxes/observability/).

## 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 `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.

[AnteriorTemplates: inicie sandboxes prontos para trabalhar](https://pethost.dev/pt/docs/sandboxes/templates/) [PróximaFaça fork de um sandbox, com memória e processos](https://pethost.dev/pt/docs/sandboxes/forks/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/pt/templates/)
- [Sobre nós](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/pt/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Termos](https://pethost.dev/terms/)
- [Privacidade](https://pethost.dev/privacy/)
- [Reembolsos](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bancos de dados

- [Postgres](https://pethost.dev/pt/postgres/)
- [Valkey](https://pethost.dev/pt/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/pt/sandboxes/)
- [Preços](https://pethost.dev/pt/sandboxes/#pricing)
- [Docs](https://pethost.dev/pt/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparativos

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/pt/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/pt/blog/coolify-cloud-vs-dokploy-cloud/)
- [Preços Railway vs Render vs Fly.io](https://pethost.dev/pt/blog/railway-vs-render-vs-fly-io-pricing/)
- [Hospedagem gerenciada de Docker Compose](https://pethost.dev/pt/blog/managed-docker-compose-hosting/)

Alternativas

- [Alternativas ao Railway](https://pethost.dev/pt/blog/railway-alternatives/)
- [Alternativas ao Heroku](https://pethost.dev/pt/blog/heroku-alternatives/)
- [Alternativas ao Dokploy](https://pethost.dev/pt/blog/dokploy-alternatives/)
- [Alternativas ao Coolify](https://pethost.dev/pt/blog/coolify-alternatives/)
- [Alternativas ao Render](https://pethost.dev/pt/blog/render-alternatives/)
- [Alternativas ao Sliplane](https://pethost.dev/pt/blog/sliplane-alternatives/)
