Documentación de Agent Sandboxes · Tareas
Secretos y salida: claves que un sandbox nunca tiene
Un sandbox ejecuta código del que quizá no te fías: el de un agente, el de un usuario, el de un paquete. Dos ajustes lo mantienen dentro de sus límites. Un secreto es una clave que el sandbox nunca tiene: ve un marcador, y el proxy de salida pone la clave real en la conexión, solo hacia los hosts que indiques. La salida es la lista de los sitios a los que puede conectarse.
SetSecretguarda un valor en el espacio de trabajo con sus hosts; una variable vinculada a él (EnvVar.secret) guarda un marcador,phs_….- El cambio: en las cabeceras de las peticiones HTTPS solo hacia los hosts del secreto, tanto
Authorizationcomox-api-key. Un valor nuevo funciona al momento. egress.allowydeny: dominios, subdominios, IP y CIDR, con un puerto cuando no sea el 80 y el 443;denygana; por defecto, cualquier sitio.- Solo salen TCP y DNS, y el DNS del sandbox solo responde los nombres que la lista permite.
Step 1: Guarda un secreto con sus hosts
Un secreto tiene un nombre (a-z, 0-9 y "-"), un valor y los hosts a los que puede enviarse el valor. Configúralo desde tu propio entorno, nunca desde un prompt ni desde un archivo del sandbox. Volver a configurarlo reemplaza su valor y sus hosts a la vez.
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: Crea un sandbox que lo vincule, detrás de una lista de destinos permitidos
Vincula una variable al secreto en el environment del sandbox, y lista en egress.allow adónde puede conectarse: aquí el índice de paquetes de Python y el host del secreto. La salida debe permitir los hosts del secreto.
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: Mira lo que ve el sandbox
Dentro, la variable guarda el marcador, una petición al host del secreto lleva la clave, y un nombre que la lista no permite ni siquiera se resuelve.
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);
La ejecución de arriba guardó una clave inventada, a la que OpenAI respondió con un 401; tu clave real responde 200. En los dos casos, la petición salió del sandbox con el valor guardado en lugar del marcador.
Step 4: Cambia la lista mientras se ejecuta
UpdateSandbox con un grupo egress reemplaza la lista entera de una vez, y cierra las conexiones que ya no permite. Un valor nuevo de un secreto no necesita nada: vuelve a llamar a SetSecret, y cada sandbox que lo vincula envía el nuevo desde su siguiente petición.
$ 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"]}}}
Cómo funciona un secreto
El valor de un secreto vive en el panel, sellado, y en la memoria de los servidores que ejecutan sandboxes que lo vinculan: nunca en el disco de un sandbox, nunca en su memoria, nunca en una respuesta de la API. Una variable vinculada a él guarda un marcador que empieza por phs_, el mismo para cada proceso del sandbox.
El proxy de salida del sandbox termina el TLS solo para los hosts del secreto, con un certificado de la propia autoridad del servidor, en la que confía el sandbox: Node, Python, curl y git apuntan a ella. En cada petición a esos hosts cambia el marcador por el valor allí donde aparezca en el valor de una cabecera: Authorization: Bearer, x-api-key, dentro de las credenciales de Authorization: Basic. Una petición a cualquier otro host lleva el marcador, que allí no vale nada. El cambio se hace solo en las cabeceras, no en el cuerpo de una petición.
- Los hosts se escriben como la salida escribe los dominios:
api.openai.com, o*.example.compara sus subdominios, con un puerto cuando no sea el 443. - Un valor nuevo funciona al momento, en cada sandbox en ejecución y en cada fork que vincula el secreto.
- Un secreto vinculado no se puede eliminar:
DeleteSecretse rechaza mientras lo vincule un sandbox que no esté eliminado. - Un espacio de trabajo tiene 100 secretos.
GetWorkspacelista sus nombres y sus hosts, nunca sus valores.
Los eventos de salida dicen, para cada host y cada minuto, qué secretos se pusieron en sus peticiones: observabilidad.
Cómo funciona la salida
El egress de un sandbox tiene dos listas. allow dice adónde puede conectarse, deny adónde no, y deny gana. Por defecto, allow es ["*"], cualquier sitio. Un grupo enviado reemplaza el grupo entero: deny enviado solo deja allow vacío, así que para bloquear unos pocos hosts envía allow ["*"] junto con ellos. Entre las dos tienen 100 entradas de 255 bytes como máximo.
| Entrada | Abre |
|---|---|
* | Cualquier sitio. |
pypi.org | Ese dominio, en los puertos 80 y 443. |
*.github.com | Sus subdominios a cualquier profundidad, no el propio github.com. |
github.com:22 | Ese dominio en ese puerto: git por SSH. |
203.0.113.7, 203.0.113.0/24 | Esas direcciones, marcadas por dirección, con :port cuando no sea el 80 y el 443. |
- De un sandbox solo salen TCP y DNS: nada de UDP, así que ni QUIC ni HTTP/3, y nada de ping, diga lo que diga la lista.
- El DNS solo responde nombres permitidos. El resolvedor del sandbox responde REFUSED a un nombre que ninguna entrada de dominio permite, sin preguntar a nadie, así que no salen datos en las consultas DNS.
- El TLS se juzga por el nombre que envía el cliente, y el proxy se conecta a la dirección que resolvió él mismo, nunca a la que eligió el sandbox. Una entrada de dominio confía en lo que se sirva en las direcciones de ese nombre, incluidos otros sitios de una CDN: una barrera que deba aguantar ahí nombra IP, o vincula un secreto al host, cuyas peticiones el proxy lee entonces una a una.
- El HTTP sin cifrar se juzga petición por petición: una petición a otro host distinto del de su conexión recibe un 421, y la conexión nueva del cliente se juzga por ese host.
- SSH y otros protocolos no nombran ningún host, y solo pasan hacia una entrada de dominio que nombre el puerto, como
github.com:22. - Siempre se rechazan: las direcciones privadas, link-local y CGNAT, el propio servidor, el puerto 25 y HTTP/2 sin TLS.
- Un rechazo que el proxy puede responder es un 403 que dice qué lo rechazó.
Cada sandbox tiene además sus propios límites: 200 conexiones nuevas por segundo tras una ráfaga de 1000, 1024 abiertas a la vez y 200 consultas DNS por segundo.
Listas que funcionan
| Para | allow |
|---|---|
| pip y uv | pypi.org, files.pythonhosted.org |
| npm | registry.npmjs.org |
| git por HTTPS y SSH | github.com, *.githubusercontent.com, github.com:22 |
| Claude Code | api.anthropic.com |
| Codex | api.openai.com |
Mira los eventos de salida de un sandbox durante un minuto de trabajo real para saber qué más necesita: cada uno dice el host, si se permitió y cuántos bytes fueron en cada sentido.
Cuando no funciona
- “Could not resolve host”: ninguna entrada permite ese nombre. Agrégalo a
allow. - Un 403 que nombra la política de salida: el host, o su puerto, no está permitido, o coincidió una entrada de
deny. SSH necesita el puerto en su entrada. - El servicio responde 401 con un secreto vinculado: la petición fue a un host que el secreto no nombra, o el cliente puso la clave en el cuerpo, donde no se hace ningún cambio, o fija sus propios certificados. Nombra el host en los
hostsdel secreto, y envía la clave en una cabecera. INVALID_ARGUMENTal crear o actualizar: la salida del sandbox no permite los hosts de un secreto vinculado, o el secreto no existe. Permítelos, o configura antes el secreto.FAILED_PRECONDITIONenDeleteSecret: un sandbox lo vincula. Desvincúlalo conUpdateSandbox, o elimina ese sandbox.RESOURCE_EXHAUSTEDconLimitReached,secrets: el espacio de trabajo tiene 100. Elimina uno que ya no vincules.
Preguntas
¿Puede un proceso del sandbox leer mi clave de API?
No. Una variable vinculada guarda un marcador; el proxy de salida, fuera de la VM, pone la clave en las peticiones hacia los hosts del secreto.
¿Qué peticiones reciben la clave real?
Las peticiones HTTPS a los hosts que nombra el secreto, en sus cabeceras. Cualquier otro host recibe el marcador.
¿Cómo bloqueo el acceso a internet de un sandbox?
Envía egress con un allow vacío: no sale nada, y el DNS no resuelve nada. Agrega solo lo que necesite el trabajo.
¿Un sandbox tiene UDP?
No. De un sandbox solo salen TCP y DNS, así que QUIC, HTTP/3 y ping no funcionan, diga lo que diga la lista.
¿Los cambios de salida se aplican a un sandbox en ejecución?
Sí, al momento: se cierran las conexiones que la lista nueva ya no permite.
Prueba Pethost Agent Sandboxes
Una prueba gratis de 7 días con 1 US$ de uso y 4 vCPU, con tarjeta. Después, un plan desde 20 US$ al mes, que incluye ese mismo importe en uso.