Español
Menú de la documentación

Documentación de Agent Sandboxes · Tareas

Secretos y salida: claves que un sandbox nunca tiene

Actualizado · 8 min de lectura

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.

En resumen
  • SetSecret guarda 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 Authorization como x-api-key. Un valor nuevo funciona al momento.
  • egress.allow y deny: dominios, subdominios, IP y CIDR, con un puerto cuando no sea el 80 y el 443; deny gana; 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.

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

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

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

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.

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

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.com para 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: DeleteSecret se rechaza mientras lo vincule un sandbox que no esté eliminado.
  • Un espacio de trabajo tiene 100 secretos. GetWorkspace lista 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.

EntradaAbre
*Cualquier sitio.
pypi.orgEse dominio, en los puertos 80 y 443.
*.github.comSus subdominios a cualquier profundidad, no el propio github.com.
github.com:22Ese dominio en ese puerto: git por SSH.
203.0.113.7, 203.0.113.0/24Esas 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

Paraallow
pip y uvpypi.org, files.pythonhosted.org
npmregistry.npmjs.org
git por HTTPS y SSHgithub.com, *.githubusercontent.com, github.com:22
Claude Codeapi.anthropic.com
Codexapi.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 hosts del secreto, y envía la clave en una cabecera.
  • INVALID_ARGUMENT al 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_PRECONDITION en DeleteSecret: un sandbox lo vincula. Desvincúlalo con UpdateSandbox, o elimina ese sandbox.
  • RESOURCE_EXHAUSTED con LimitReached, 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.

Empezar la prueba gratis