Español
Empezar

Agent Sandboxes Comandos, archivos y terminal

Un sandbox de ejecución de código para agentes de IA

Tu modelo escribe código, un sandbox lo ejecuta y la salida vuelve en la misma llamada. Comandos, archivos y terminales son una sola API, y responde el servidor donde se ejecuta el sandbox, no el panel.

Ejecución de código en una llamada

Cada sandbox es una microVM Firecracker con su propio kernel Linux y root dentro, iniciada desde nuestra plantilla base en unos 0,15 s: Ubuntu 24.04 con herramientas de compilación, Python 3, Node.js 22 y Docker. run_command ejecuta un comando con bash -lc como user, que tiene sudo, o como root, en el directorio que indiques. La llamada espera hasta 45 segundos a que el comando termine y responde con su código de salida y los últimos 32 KiB de su stdout y su stderr.

Tres campos cambian lo que espera la llamada:

  • wait_for_port responde en cuanto algo escucha en un puerto, mientras el comando sigue en ejecución: npm run dev y el 5173.
  • wait_seconds=0 responde en cuanto el comando se inició. get_command vuelve a esperarlo, y watch_command transmite su salida, primero los últimos 64 KiB y luego en tiempo real.
  • timeout_seconds termina un comando que dura demasiado. Sin él, solo stop_command lo termina: SIGTERM, y SIGKILL 10 s después.

Cada respuesta dice cuántos bytes escribió el comando; devuélvelos y la siguiente respuesta solo traerá lo nuevo. Con un request_id, un reintento en las 24 horas siguientes no vuelve a ejecutar nada y responde lo que hizo la primera llamada. list_commands muestra lo que se ejecuta ahora, comandos escritos por SSH incluidos, y se conservan los últimos 100 que terminaron.

from pethost.sandboxes import FileChange, Sandboxes, TextEdit

sandboxes = Sandboxes()  # lee PETHOST_TOKEN
box = sandboxes.create_sandbox()
code = "x = 1\nprint(x * 42)\n"
sandboxes.write_files(box.sandbox_id, changes=[FileChange(path="app.py", text=code)])
out = sandboxes.run_command(box.sandbox_id, command="python3 app.py", timeout_seconds=30)
print(out.exit_code, out.stdout)  # 0 42

edit = TextEdit(old_text="x = 1", new_text="x = 2")
sandboxes.write_files(box.sandbox_id, changes=[FileChange(path="app.py", edit=edit)])
server = sandboxes.run_command(box.sandbox_id, command="python3 -m http.server 8000",
                               wait_for_port=8000)
print(server.state.name)  # RUNNING: respondió en cuanto el puerto 8000 escuchaba
pethost sandbox new --name tests --size small
pethost sandbox cp ./app tests:/home/user/app
pethost sandbox run tests --cwd /home/user/app -- python3 -m unittest
pethost sandbox open tests --terminal

Archivos: lotes y ediciones exactas

write_files recibe una lista de cambios y los hace en orden: escribir el texto o los bytes de un archivo, reemplazar un texto que aparece exactamente una vez en él, mover, eliminar, crear un directorio, cambiar un modo. Los directorios padre que faltan se crean. Se detiene en el primer cambio que falla y dice cuál, con un motivo sobre el que decidir, como que el texto a reemplazar no está. Así, una edición solo se aplica donde está su texto. Una petición lleva hasta 17 MiB.

read_file lee hasta 1 MiB desde cualquier posición, list_files lista un directorio con la profundidad que pidas, y watch_files transmite cada cambio dentro de uno. Un archivo de cualquier tamaño se mueve con un enlace de create_link: una URL de descarga envía el archivo, o un directorio como .tar; una URL de subida acepta un PUT. Cada una funciona una vez.

Una terminal en el navegador

create_link con una terminal da una página que ejecuta bash, o un comando como claude, y un WebSocket en la misma URL que lleva sus bytes, para una terminal dentro de tu propio producto. Un enlace dura una hora por defecto y un día como máximo.

Qué se ejecuta dentro

Docker funciona en cada sandbox: dockerd se inicia con la primera conexión a su socket y guarda las imágenes en el disco del sandbox, así que sobreviven a una detención y una plantilla las lleva consigo. Lo demás viene de apt, con sudo.

Las llamadas van directamente al servidor del sandbox, que el SDK encuentra por ti. El primer comando tras una creación responde en 29 a 48 ms. En un servidor con 74 sandboxes, cada uno compilando un proyecto JavaScript y esperando entre compilaciones como hace un agente, un comando trivial tardó 6 ms (28 ms en el percentil 95).

Límites y precios

QuéLímite
Llamadas a la vez, por sandbox64; un write_files cuenta como 16
Una petición1 MiB; write_files, 17 MiB
Una respuestaunos 64 KiB; read_file, 1 MiB; cualquier tamaño con un enlace
Salida en una respuestalos últimos 32 KiB de stdout y de stderr

Los comandos, los archivos y los enlaces no tienen precio propio: pagas los segundos en ejecución del sandbox, desde 0,018 US$ la hora para SMALL (2 vCPU, 4 GiB) hasta 0,144 US$ para XLARGE (16 vCPU, 32 GiB), cada ejecución redondeada al segundo y 10 s como mínimo. Tras 5 minutos inactivo, se pausa al 30 % de eso. Cómo funciona la facturación por segundo.

Cómo se compara

El 21 de noviembre de 2026, E2B cobraba 0,1656 US$ la hora por un sandbox de 2 vCPU y 4 GiB, igual que Daytona; el SMALL de Pethost, del mismo tamaño, cuesta 0,018 US$. Las sesiones de E2B duraban hasta 1 hora en su plan Hobby y 24 horas en Pro, y las de Vercel Sandbox, 45 minutos en Hobby y 24 horas en Pro. Un sandbox de Pethost no tiene límite de cuánto tiempo vive.

Leer la documentación

Preguntas

¿Qué lenguajes puede ejecutar un sandbox de ejecución de código?

Cualquier cosa que funcione en Linux. Python 3 y Node.js 22 vienen instalados, Docker funciona y apt instala lo demás. Guarda un sandbox con tus herramientas como plantilla y los sandboxes nuevos partirán con ellas.

¿Cuánto tiempo puede durar un comando?

Lo que necesite: una llamada espera hasta 45 segundos, y luego lees su salida o la recibes en tiempo real. Tras 5 minutos inactivo, un sandbox se pausa con el comando en memoria, que sigue con la siguiente llamada. Un comando iniciado con keep_awake se ejecuta de principio a fin, igual que uno que sigues con watch_command.

¿Puede el código llegar a internet?

Sí, por TCP: por defecto un sandbox puede conectarse a cualquier lugar. Una lista de destinos permitidos lo reduce a los dominios, las IP y los puertos que indiques. Ningún paquete UDP sale de un sandbox.

¿Cómo muevo archivos grandes?

Con un enlace de descarga o de subida, de cualquier tamaño, o con scp por SSH.

Relacionado

Dale a tu agente una VM en 0,15 s

Empezar la prueba gratis