---
title: "Secretos y salida: claves que un sandbox nunca tiene | Pethost Agent Sandboxes"
description: "Dale a un sandbox claves de API que nunca tiene, que el proxy de salida pone solo para los hosts que indiques, y limita adónde puede conectarse."
---

[Documentación de Agent Sandboxes](https://pethost.dev/es/docs/sandboxes/) · Tareas

# Secretos y salida: claves que un sandbox nunca tiene

Actualizado 22 de noviembre de 2026 · 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](https://pethost.dev/es/docs/sandboxes/observability/).

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

[AnteriorPlantillas: sandboxes que se inician listos para trabajar](https://pethost.dev/es/docs/sandboxes/templates/) [SiguienteHaz un fork de un sandbox, memoria y procesos incluidos](https://pethost.dev/es/docs/sandboxes/forks/)

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

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Plantillas](https://pethost.dev/es/templates/)
- [Sobre nosotros](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/es/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Términos](https://pethost.dev/terms/)
- [Privacidad](https://pethost.dev/privacy/)
- [Reembolsos](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bases de datos

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

Agent Sandboxes

- [Sandboxes](https://pethost.dev/es/sandboxes/)
- [Precios](https://pethost.dev/es/sandboxes/#pricing)
- [Docs](https://pethost.dev/es/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparativas

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/es/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/es/blog/coolify-cloud-vs-dokploy-cloud/)
- [Precios de Railway vs Render vs Fly.io](https://pethost.dev/es/blog/railway-vs-render-vs-fly-io-pricing/)
- [Hosting gestionado para Docker Compose](https://pethost.dev/es/blog/managed-docker-compose-hosting/)

Alternativas

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