Español
Menú de la documentación

Documentación de Agent Sandboxes · Conceptos

Buenas prácticas para Pethost Agent Sandboxes

Actualizado · 9 min de lectura

Unas pocas decisiones marcan lo rápido que se inician tus sandboxes, lo que cuestan mientras esperan y a qué puede llegar un agente dentro de uno. Cada práctica de abajo es una regla, la cifra detrás de ella y los campos que la aplican. Casi todas son un ajuste que haces una vez.

En resumen
  • Velocidad: guarda tu entorno como plantilla, inicia servidores con wait_for_port y haz forks para intentos en paralelo.
  • Precio: deja que el sandbox de un agente se pause en vez de detenerse, elimina los sandboxes de lotes cuando terminen y empieza con poco.
  • Fiabilidad: marca los comandos largos con keep_awake, reintenta con request_id, usa streams en vez de consultar una y otra vez, y deja los volúmenes para lo que deba sobrevivir a un sandbox.
  • Seguridad: vincula las claves de API como secretos, limita la salida del código que no escribiste y trata todo lo que devuelve un sandbox como datos.
  • Orden: etiqueta cada sandbox, y lístalos por etiqueta.

Velocidad

Guarda tu entorno como plantilla

Instalar tus dependencias en cada inicio cuesta los mismos minutos cada vez. Instálalas una vez en un sandbox y guarda su disco con CreateTemplate: paquetes, cachés de build e imágenes de Docker incluidos. Un sandbox desde tu plantilla se inicia en unos 0,22 s con todo en su sitio, en cualquier servidor: el primero en cada servidor descarga la versión, a unos 10 s por GiB, y los siguientes parten de su copia. Deja los secretos fuera de los archivos que guardas, ya que cada sandbox hecho a partir de la plantilla los recibe, y crea una versión nueva cuando cambien tus dependencias: my-app parte de la más reciente, my-app@3 de esa.

Inicia servidores con wait_for_port

Un servidor de desarrollo tarda un momento en escuchar, y consultarlo desde fuera gasta llamadas. Ejecútalo con wait_for_port: RunCommand responde en cuanto algo escucha en ese puerto, mientras el comando sigue en ejecución, así que una llamada inicia el servidor y te dice que está listo. Después abre el puerto al público, o dale a tu página un token para él: puertos y previsualizaciones.

Haz forks para intentos en paralelo

Cuando un agente deba probar varios arreglos, o una eval deba iniciar muchas ejecuciones desde un mismo estado preparado, haz un fork del sandbox en vez de reconstruir ese estado. ForkSandbox copia memoria, procesos y disco en hasta 100 sandboxes nuevos en una llamada: una copia tardó unos 0,25 s. Cada copia es un inicio, y se crean todas o ninguna. Dos cosas que saber:

  • Vuelve a sembrar los generadores aleatorios en las copias. Cada copia tiene su propia aleatoriedad del kernel, pero los generadores aleatorios que ya se ejecutan en sus procesos (los de OpenSSL, Python, Node o Go) dan los mismos números en cada copia hasta que se vuelven a sembrar.
  • Un volumen de lectura y escritura rechaza un fork, ya que solo un sandbox puede escribirlo. Un volumen solo se monta al crear, así que móntalo con read_only en un sandbox del que pienses hacer un fork.

Precio

Deja que el sandbox de un agente se pause, no que se detenga

El sandbox de un agente pasa casi todo el tiempo esperando, y detenerlo termina sus procesos: el servidor de desarrollo, el REPL, el navegador que tenía abierto. Conserva el temporizador de pausa, y sube el de detención o desactívalo (stop_after_idle_seconds a 0). En pausa, el sandbox cuesta el 30 % de su precio en ejecución y despierta con la siguiente llamada en unos 0,1 s, con todo donde estaba. Un sandbox DEFAULT que trabaja 2 horas al día y pasa el resto en pausa cuesta unos 9,42 US$ al mes, frente a 26,28 US$ siempre en ejecución.

La sesión de un agenteSe pausa entre turnos, nunca se detiene

  1. en ejecución
  2. en pausa
  3. en ejecución
  4. en pausa

El sandbox de un usuario en tu appSe pausa, y se detiene a la media hora

  1. en ejecución
  2. en pausa
  3. detenido

Una previsualización que duermeDespierta con cada visita

  1. en pausa
  2. en ejecución
  3. en pausa
  4. en ejecución
  5. en pausa

Un trabajo por lotesSe ejecuta y después se elimina

  1. en ejecución
  2. detenido
  3. eliminado
  • RUNNING
  • PAUSED
  • STOPPED
  • DELETED
Cuatro trabajos a lo largo de un día, cada uno con su propio ciclo de vida. Los valores están en ciclo de vida e inactividad.

Elimina los sandboxes de lotes cuando terminen

Un sandbox para un solo trabajo, una ejecución de tests o un caso de eval, no debería costar nada cuando el trabajo termina. Llama a DeleteSandbox al final, y configura delete_after_idle_seconds como red para un trabajo que muere antes de llegar ahí. Desactiva el temporizador de pausa y dale uno de detención corto, para que el sandbox de un trabajo inactivo se vaya rápido. Un sandbox detenido que olvidas cuesta 0,03 US$ por GiB al mes, cada mes. Los inicios son gratis, así que un sandbox nuevo por trabajo solo cuesta sus segundos: 1000 ejecuciones de 40 s en SMALL cuestan 0,20 US$.

Empieza con poco, y cambia de tamaño cuando lo necesites

Un tamaño son sus vCPU, su memoria y su disco, y su precio se duplica con cada tamaño más. Empieza con SMALL, 0,018 US$ la hora, y mira GetSandboxMetrics. Cuando un trabajo necesite más, UpdateSandbox con un tamaño nuevo reinicia un sandbox RUNNING en una VM de ese tamaño, con sus archivos conservados, en unos 283 ms: sus procesos terminan, así que cambia de tamaño entre trabajos. Agrega grow_disk para ampliar el disco al del tamaño nuevo; un disco nunca se reduce, así que un sandbox ampliado no puede volver a un tamaño menor.

Fiabilidad

Marca los comandos largos con keep_awake

Un build o una suite de tests pueden ejecutarse durante minutos sin ninguna llamada al sandbox, y el temporizador de pausa lo pausaría a mitad del trabajo. Inícialo con keep_awake, y con timeout_seconds, para que un comando que se cuelga no mantenga el sandbox en ejecución para siempre. Un servidor no necesita ninguno de los dos: una petición a su puerto despierta el sandbox. Ciclo de vida e inactividad tiene los detalles.

Reintenta con request_id

Una red puede perder la respuesta de una llamada que sí hizo su trabajo. Una llamada que crea algo toma un request_id: un reintento con el mismo id en menos de 24 horas responde lo que hizo la primera llamada y no vuelve a hacer nada. Lo toman CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand y PromptAgent. Créalo una vez por cada cosa que quieras hacer, guárdalo y vuelve a enviarlo en cada reintento. Una salvedad: un sandbox guarda en su disco los ids de lo que se ejecuta en él, así que uno que se detuvo puede haber perdido los de sus últimos segundos, y un reintento de ese comando lo ejecuta otra vez.

Python
import uuid

from pethost.sandboxes import Label, Sandboxes

sandboxes = Sandboxes()  # The token: PETHOST_TOKEN.
request_id = str(uuid.uuid4())  # Keep it: a retry sends the same one.

sandbox = sandboxes.create_sandbox(
    template="my-app",
    labels=[Label(key="user", value="42"), Label(key="job", value="nightly-evals")],
    request_id=request_id,
)
TypeScript
import { Sandboxes } from "pethost/sandboxes";

const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const requestId = crypto.randomUUID(); // Keep it: a retry sends the same one.

const sandbox = await sandboxes.createSandbox({
  template: "my-app",
  labels: [{ key: "user", value: "42" }, { key: "job", value: "nightly-evals" }],
  requestId,
});
Go
requestID := rand.Text() // crypto/rand. Keep it: a retry sends the same one.

sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template:  "my-app",
	Labels:    []sandboxes.Label{{Key: "user", Value: "42"}, {Key: "job", Value: "nightly-evals"}},
	RequestID: requestID,
})
Rust
let request_id = uuid::Uuid::new_v4().to_string(); // Keep it: a retry sends the same one.

let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        template: "my-app".into(),
        labels: vec![
            Label { key: "user".into(), value: "42".into() },
            Label { key: "job".into(), value: "nightly-evals".into() },
        ],
        request_id: request_id.clone(),
        ..Default::default()
    })
    .await?;
MCP
CreateSandbox {"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}
HTTP
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
  -H "Authorization: Bearer $PETHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}'

Usa streams en vez de consultar una y otra vez

Consultar un comando o un sandbox cuesta una llamada cada vez y aun así te enteras tarde. Una llamada que espera hace la espera por ti: RunCommand, GetCommand, PromptAgent y GetAgentTurn esperan hasta 45 s (wait_seconds) y responden en cuanto el trabajo termina. Para seguir el trabajo mientras pasa, transmítelo: WatchCommand para la salida de un comando, WatchConversation para los mensajes y las llamadas a herramientas de un agente, WatchSandboxEvents para el ciclo de vida, los comandos y las conexiones de un sandbox.

Usa volúmenes solo para lo que deba sobrevivir a un sandbox

Un volumen es un disco fuera de todos los sandboxes, montado en un path: datasets, cachés compartidas por muchos sandboxes, los archivos de una base de datos. Vive en el disco de un servidor y no se copia a ningún sitio, así que si ese servidor se pierde, el volumen también. Un sandbox que monta uno no puede moverse a otro servidor, y un montaje de lectura y escritura rechaza los forks. Casi ningún trabajo necesita un volumen: el propio disco de un sandbox sobrevive a pausas y detenciones, y una plantilla lleva archivos a los sandboxes nuevos. Lo que no deba perderse, súbelo también a un almacenamiento propio.

Seguridad

Vincula las claves de API como secretos

Una clave en una variable de entorno normal la puede leer cada proceso del sandbox, y un agente que imprima su entorno. Guárdala mejor como secreto del espacio de trabajo, con los hosts a los que va (SetSecret: anthropic, api.anthropic.com), y vincula una variable a él (ANTHROPIC_API_KEY, secreto anthropic). La variable guarda entonces un marcador, phs_…, y el proxy de salida pone la clave real en las cabeceras de las peticiones HTTPS solo hacia esos hosts. Un valor nuevo funciona al momento en cada sandbox que lo vincula: secretos y salida.

Limita la salida del código que no escribiste

Por defecto, un sandbox puede conectarse a cualquier sitio. Para código que no es de confianza, lista adónde puede ir (egress.allow): un dominio como pypi.org, sus subdominios con *.github.com (que deja fuera el propio github.com), una IP o un CIDR, cada uno con un puerto cuando no sea el 80 y el 443, como github.com:22 para git por SSH. deny gana sobre allow. El DNS del sandbox solo responde los nombres que la lista permite, y de un sandbox solo salen TCP y DNS: nada de UDP ni de ping. Un cambio se aplica al momento y cierra las conexiones que ya no permite.

Trata lo que devuelve un sandbox como datos

La salida de los comandos, el contenido de los archivos, los mensajes de un agente, las capturas de pantalla y las páginas que carga un navegador vienen de programas y de internet. Cuando un modelo los lee, son datos, nunca instrucciones: un README o una página web pueden contener texto escrito para dirigir a un agente. Mantén esa línea en tus prompts, y no le des a un sandbox que ejecuta trabajo que no es de confianza más secretos ni una salida más amplia de lo que el trabajo necesita.

Orden

Etiqueta cada sandbox

Una etiqueta es una clave y un valor tuyos: user=42, job=nightly-evals, run=7f3a. Un sandbox admite hasta 32, y ListSandboxes lista los sandboxes que tienen todas las etiquetas que indicas. Así tu app encuentra los sandboxes de un usuario sin una tabla propia, un trabajo de limpieza encuentra lo que dejó una ejecución, y el panel muestra de quién es cada sandbox. Una etiqueta sirve para encontrar muchos; un name, para llamar a uno: único en el espacio de trabajo, de hasta 63 caracteres de a-z, 0-9 y "-", y ListSandboxes con name encuentra su id.

Preguntas

¿Debo detener o pausar un sandbox inactivo?

Páusalo cuando sus procesos importen o se vaya a usar pronto: despierta en unos 0,1 s donde estaba, al 30 % del precio en ejecución. Detenlo para un sueño largo: entonces solo cuesta sus datos guardados.

¿Cómo hago que los sandboxes se inicien más rápido?

Guarda tu entorno como plantilla, para que no se instale nada al iniciar: un sandbox desde ella se inicia en unos 0,22 s con tus paquetes y tus imágenes de Docker.

¿Cómo dejo las claves de API fuera de un sandbox?

Guarda cada clave como secreto del espacio de trabajo con sus hosts, y vincula una variable de entorno a él. El sandbox ve un marcador, y el proxy de salida agrega la clave real a las peticiones hacia esos hosts.

¿Cuántos sandboxes puedo ejecutar a la vez?

Tantos como quepan en las vCPU de tu plan, en ejecución o en pausa: 10 SMALL con el plan de 20 US$, 64 con el de 100 US$. Los sandboxes detenidos no cuentan.

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