Documentación de Agent Sandboxes · Primeros pasos
Cómo funcionan Pethost Agent Sandboxes
Un sandbox es una VM Linux que tu código o tu agente inicia en unos 0,15 s, usa a través de una API y deja tranquila. Cuando no pasa nada en él, se pausa con su memoria y sus procesos, y más tarde se detiene solo con su disco. La siguiente llamada lo despierta donde estaba. Esta página es el modelo: qué es un sandbox, sus tres estados, qué lo mueve entre ellos y dónde vive cada byte.
- Una microVM por sandbox: Firecracker, su propio kernel, root dentro, Ubuntu con Python, Node.js, Docker, tres agentes de programación y Chrome.
- Tres estados: RUNNING en la memoria de su servidor, PAUSED en el disco de su servidor con la memoria y los procesos conservados, STOPPED en almacenamiento de objetos solo con su disco.
- Despierta al usarse: cualquier llamada a un sandbox en pausa, un inicio de sesión SSH o una petición a uno de sus puertos lo reanuda en unos 0,1 s.
- Dos API: el panel guarda el registro de cada sandbox, y el propio servidor del sandbox ejecuta lo que pasa dentro. Los SDK y la CLI ocultan la diferencia.
- Facturado por segundo en cada estado: facturación.
Qué es un sandbox
Un sandbox es una máquina virtual, hecha a partir de una plantilla. Dentro eres root, y los comandos se ejecutan como el usuario user, que tiene sudo sin contraseña, en /home/user. Su hostname es su id: 16 caracteres, letras minúsculas y dígitos.
Nuestra plantilla, base, tiene Ubuntu 24.04 con herramientas de build y git, Python 3, Node.js 22, Docker, los agentes de programación Claude Code, Codex y OpenCode, y un escritorio con Google Chrome. Dos de ellos solo se inician con su primer uso, y no cuestan nada hasta entonces: el escritorio, con la primera captura de pantalla o el primer enlace al escritorio (unos segundos), y el daemon de Docker, con la primera conexión a /var/run/docker.sock.
Aislamiento: una microVM Firecracker por sandbox
Cada sandbox es su propia microVM Firecracker, con su propio kernel Linux. Firecracker ejecuta cada VM dentro de su jailer: su propio chroot, un usuario sin privilegios, un cgroup, un filtro seccomp y su propio network namespace. El invitado es tuyo, root y kernel incluidos; el host decide lo que recibe.
- El host fija su tamaño. Una VM recibe del servidor las vCPU y la memoria de su tamaño, y nada de lo que diga el invitado lo cambia.
- Su propia identidad. Cada sandbox recibe aleatoriedad del kernel nueva, su propio hostname y su propio machine-id, aunque se inicie desde el mismo snapshot que otro.
- Ningún secreto dentro. Los secretos del espacio de trabajo nunca entran en una VM, y los tokens de API tampoco: a un sandbox se llega con un token solo para ese sandbox, que caduca.
Tamaños
Un sandbox tiene uno de cuatro tamaños, durante toda la vida de su VM:
| Tamaño | vCPU | Memoria | Disco |
|---|---|---|---|
| SMALL | 2 | 4 GiB | 10 GiB |
| DEFAULT | 4 | 8 GiB | 20 GiB |
| LARGE | 8 | 16 GiB | 40 GiB |
| XLARGE | 16 | 32 GiB | 80 GiB |
El disco es lo que el sandbox puede escribir: los archivos de la propia plantilla no cuentan. Un tamaño nuevo (UpdateSandbox) reinicia un sandbox RUNNING en una VM de ese tamaño, con sus archivos conservados y sus procesos terminados; uno STOPPED toma el tamaño nuevo en su siguiente inicio, y uno PAUSED debe reanudarse o detenerse antes. Un tamaño nuevo conserva el disco salvo que indiques grow_disk, que lo amplía al del tamaño nuevo. Un disco nunca se reduce.
Plantillas
Una plantilla son los archivos con los que se inicia un sandbox. La nuestra es base, reconstruida cada mes y al momento ante un arreglo de seguridad. La tuya es el disco de un sandbox guardado con CreateTemplate: sus archivos, los paquetes que instalaste y sus imágenes de Docker. Una plantilla no conserva memoria, ni procesos, ni conversaciones de agentes: un sandbox hecho a partir de ella arranca de cero.
Cada guardado es una versión nueva, name@1, name@2, y un sandbox iniciado desde name toma la más reciente. Cualquier servidor inicia sandboxes desde cualquier versión. El min_size de una versión es el tamaño más pequeño en cuyo disco cabe lo que guardó. Un sandbox desde tu propia plantilla se inicia en unos 0,22 s una vez que su servidor tiene la versión; el primero en cada servidor la descarga, a unos 10 s por GiB: plantillas.
Dos API: el panel y el servidor del sandbox
Responden dos servicios, según lo que sabe cada uno:
- SandboxService es el panel, en
https://console.pethost.dev, al que se llama con tu token de API. Guarda el espacio de trabajo y cada sandbox como un registro: creación, ajustes, pausa, reanudación, fork, eliminación, plantillas, volúmenes, eventos y uso. - SandboxRuntimeService es el propio servidor del sandbox, en la
urlde su conexión, al que se llama con un token de conexión solo para ese sandbox. Ejecuta lo que pasa dentro: comandos, archivos, el escritorio, agentes de programación y enlaces.
Los SDK y la CLI se conectan por ti: run_command es una llamada, y el SDK encuentra el servidor y mantiene el token al día. Las llamadas al runtime van directas al servidor, así que el panel nunca está en el camino de lo que se ejecuta dentro de un sandbox, y un servidor ejecuta sus sandboxes sin el panel.
Los tres estados
En la memoria de su servidor
Ejecuta tus procesos y responde a cada llamada.
0,036 US$ la hora, DEFAULT
Inactivo 5 min, o PauseSandbox
Cualquier llamada, inicio de sesión SSH o petición a un puerto, en unos 0,1 s
En el disco de su servidor
Conserva memoria, procesos y disco, y su sitio en el servidor.
0,0108 US$ la hora, DEFAULT
Inactivo 30 min, o StopSandbox
En almacenamiento de objetos
Conserva su disco; sus procesos terminan.
0,03 US$ por GiB al mes de sus propios datos
ResumeSandbox lo arranca de nuevo: unos 0,2 s con su disco en el servidor, unos 10 s por GiB desde almacenamiento de objetos
| Estado | Dónde vive | Qué conserva | Cómo despierta |
|---|---|---|---|
| RUNNING | La memoria de su servidor | Todo, en ejecución | Está despierto |
| PAUSED | El disco de su servidor | Memoria, procesos, disco | Con la siguiente llamada, inicio de sesión SSH o petición a un puerto, en unos 0,1 s; nunca se rechaza por falta de espacio |
| STOPPED | Almacenamiento de objetos, y el disco de su servidor mientras haya espacio | Su disco | Con ResumeSandbox, o como uno en pausa con wake_when_stopped |
| DELETED | En ningún sitio | Su registro durante 30 días, sus eventos y métricas durante un día | Nunca |
Por qué existe PAUSED
La VM de un agente pasa casi todo el tiempo esperando: a que el modelo piense, a que una persona lea la respuesta, al siguiente mensaje. Detenerla termina sus procesos, y con ellos el servidor de desarrollo, el REPL, el estado de la shell y el navegador abierto que usaba el agente. Mantenerla RUNNING paga el precio completo por esperar.
PAUSED lo conserva todo, memoria y procesos incluidos, por el 30 % del precio en ejecución, y el servidor guarda el sitio del sandbox, así que una reanudación nunca se rechaza por falta de espacio. Tu código no hace nada para despertarlo: la siguiente llamada al sandbox lo reanuda primero, en unos 0,1 s, y la llamada se ejecuta como si el sandbox nunca se hubiera detenido. Un sandbox en pausa tarda 41 ms en su servidor en reanudarse, y un comando enviado a uno responde en unos 80 ms.
Qué mueve un sandbox
| De | A | Qué lo mueve |
|---|---|---|
| RUNNING | PAUSED | Su temporizador de pausa; PauseSandbox; su servidor con poca memoria, si lleva un minuto inactivo; el reinicio de la máquina de su servidor (MAINTENANCE, que no cuenta nada) |
| PAUSED | RUNNING | Cualquier llamada al runtime, un inicio de sesión SSH o una petición a un puerto (WAKE); ResumeSandbox |
| RUNNING o PAUSED | STOPPED | Su temporizador de detención; StopSandbox; su servidor con poco disco (uno en pausa); un espacio de trabajo sin nada con qué pagar (UNPAID); que falle su VM o su servidor (CRASH) |
| STOPPED | RUNNING | ResumeSandbox; una llamada, un inicio de sesión SSH o una petición a un puerto solo con wake_when_stopped, y nunca tras un CRASH |
| Cualquiera | DELETED | DeleteSandbox; su temporizador de eliminación; la pérdida de su servidor, para un sandbox sin copia en almacenamiento de objetos |
Cada cambio tiene un motivo, state_reason, y unas palabras para personas, state_message. Ciclo de vida e inactividad dice qué cuenta como actividad y cómo configurar los temporizadores.
Qué despierta un sandbox
Cualquier llamada de SandboxRuntimeService, un inicio de sesión SSH o una petición a uno de sus puertos reanuda primero un sandbox PAUSED, en su propio servidor. Un sandbox STOPPED solo despierta así cuando su ciclo de vida dice wake_when_stopped. Sin eso:
- una llamada al runtime responde
FAILED_PRECONDITIONcon el detalleStopped; - una petición a un puerto responde HTTP 503, “stopped: resume it”;
- solo
ResumeSandboxlo inicia.
Un sandbox detenido por un CRASH solo vuelve a iniciarse con ResumeSandbox. Mientras el disco de un sandbox detenido se trae de vuelta desde almacenamiento de objetos, las llamadas a él responden UNAVAILABLE con Restoring, y ResumeSandbox espera hasta 45 s y luego dice cuánto lleva la descarga (Sandbox.restore).
Dónde viven tus datos
| Qué | Pausa | Detención | Fork | Plantilla | Eliminación |
|---|---|---|---|---|---|
| Memoria | Se conserva | Se pierde | Se copia | No se guarda | Desaparece |
| Procesos en ejecución | Se conservan | Terminan | Se copian, en ejecución | No se guardan | Desaparecen |
| Archivos e imágenes de Docker | Se conservan | Se conservan | Se copian | Se guardan | Desaparecen |
| Conversaciones de agentes | Se conservan | Se conservan | Se copian | No se guardan | Desaparecen |
El disco de un sandbox detenido se copia a almacenamiento de objetos en la UE un minuto después de detenerse, en fragmentos cifrados con una clave solo para ese sandbox; la memoria nunca se copia allí. Su servidor guarda su propia copia mientras tiene espacio. Un volumen es distinto: vive en el disco de un servidor y no se copia a ningún sitio, así que guarda también en otro lugar lo que deba sobrevivir a la pérdida de un servidor.
Traslados y servidores perdidos
Un sandbox STOPPED con una copia al día y sin volumen se inicia en otro servidor cuando el suyo no tiene espacio para él, y sus direcciones se mueven con él: la url de la conexión, las URL de sus puertos y su ssh_command. Un sandbox PAUSED nunca se mueve: se reanuda en el servidor que tiene su memoria.
Si se pierde un servidor, cada uno de sus sandboxes con copia pasa a STOPPED desde su última copia y se inicia en otro servidor en su siguiente ResumeSandbox. Un sandbox sin copia se elimina, igual que los volúmenes de ese servidor.
Preguntas
¿Un sandbox es un contenedor?
No. Cada sandbox es una microVM Firecracker con su propio kernel Linux, y dentro eres root. Puedes ejecutar contenedores de Docker dentro de un sandbox.
¿Qué pasa con mis procesos cuando un sandbox se pausa?
Se congelan donde están y conservan su memoria, sus archivos abiertos y su estado. La siguiente llamada, inicio de sesión SSH o petición a un puerto los reanuda en unos 0,1 s, como si nada hubiera pasado.
¿Puede un sandbox en pausa no despertar por falta de espacio?
No. Su servidor le guarda el sitio mientras está en pausa, así que una reanudación nunca se rechaza por falta de espacio. A uno detenido sí puede pasarle: entonces ResumeSandbox puede iniciarlo en otro servidor.
¿Dónde están mis archivos cuando un sandbox está detenido?
En su disco, copiado a almacenamiento de objetos en la UE, cifrado con una clave para ese sandbox, y en su servidor mientras haya espacio. Vuelven tal como estaban cuando se reanuda.
¿Una plantilla conserva los procesos en ejecución?
No. Una plantilla solo guarda el disco: archivos, paquetes e imágenes de Docker. Un sandbox hecho a partir de ella arranca de cero, sin ningún proceso ni conversación de agente del sandbox desde el que se guardó. Para copiar un sandbox en ejecución, haz un fork.
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.