Documentación de Agent Sandboxes · Tareas
Plantillas: sandboxes que se inician listos para trabajar
Una plantilla es aquello desde lo que se inicia un sandbox. La nuestra, base, tiene las herramientas; la tuya es el disco de un sandbox guardado tal como está, con los paquetes que instalaste, tu código y sus imágenes de Docker. Un sandbox desde ella se inicia en unos 0,22 s sin nada que instalar.
CreateTemplateguarda el disco y los ajustes de un sandbox como una versión nueva,my-app@1,my-app@2, mientras el sandbox sigue en ejecución.- SAVING, y después READY en unos 1,5 s para una pequeña, y unos 10 s por GiB de lo que tiene de propio.
CreateSandboxcon"my-app"parte de su versión READY más reciente, en cualquier servidor.- Solo archivos: una plantilla no conserva memoria, ni procesos, ni conversaciones de agentes. No se factura; tu plan limita su tamaño.
Step 1: Prepara un sandbox
Crea un sandbox desde base y prepáralo como debería estar cada uno nuevo: clona tu código, instala sus dependencias, descarga las imágenes de Docker que ejecuta, calienta las cachés (comandos y archivos). Sus ajustes también cuentan: la plantilla toma el ciclo de vida, la salida, los puertos públicos y el entorno del sandbox tal como están ahora, y los sandboxes desde ella empiezan con ellos salvo que su creación diga otra cosa.
Step 2: Guárdalo como plantilla
CreateTemplate responde la versión nueva en SAVING en milisegundos, en cuanto tiene el disco tal como está: el sandbox sigue en ejecución. Después, el servidor reduce la versión a lo que contiene y la sube. Espera a READY antes de partir de esa versión.
import time
from pethost.sandboxes import TemplateState
version = sandboxes.create_template("my-app", sandbox_id=sandbox_id, description="Node 22 and our dependencies")
while version.state == TemplateState.SAVING:
time.sleep(1)
version = sandboxes.get_template(f"my-app@{version.version}")
print(version.name, version.version, version.state.name, version.min_size.name, version.size_bytes)
# my-app 1 READY SMALL 25447048
let version = await sandboxes.createTemplate({
name: "my-app",
sandboxId,
description: "Node 22 and our dependencies",
});
while (version.state === TemplateState.SAVING) {
await new Promise((resolve) => setTimeout(resolve, 1000));
version = await sandboxes.getTemplate({ template: `my-app@${version.version}` });
}
console.log(version.name, version.version, version.state, version.minSize, version.sizeBytes);
version, err := client.CreateTemplate(ctx, &sandboxes.CreateTemplateRequest{
Name: "my-app",
SandboxID: id,
Description: "Node 22 and our dependencies",
})
for err == nil && version.State == sandboxes.TemplateStateSaving {
time.Sleep(time.Second)
version, err = client.GetTemplate(ctx, &sandboxes.GetTemplateRequest{Template: fmt.Sprintf("my-app@%d", version.Version)})
}
if err != nil {
log.Fatal(err)
}
fmt.Println(version.Name, version.Version, version.State, version.MinSize, version.SizeBytes)
let mut version = sandboxes
.create_template(CreateTemplateRequest {
name: "my-app".into(),
sandbox_id: id.clone(),
description: "Node 22 and our dependencies".into(),
..Default::default()
})
.await?;
while matches!(version.state, TemplateState::Saving) {
tokio::time::sleep(std::time::Duration::from_secs(1)).await;
let template = format!("my-app@{}", version.version);
version = sandboxes.get_template(GetTemplateRequest { template, ..Default::default() }).await?;
}
println!("{} {} {:?} {:?} {}", version.name, version.version, version.state, version.min_size, version.size_bytes);
$ pethost sandbox template save api-dev my-app --description 'Node 22 and our dependencies'
✓ Saving my-app@2: it is ready once uploaded. See: pethost sandbox template show my-app@2
my-app@2
$ pethost sandbox template ls my-app
my-app@2 ready 68 MB 55 s ago Node 22 and our dependencies
my-app@1 ready 24 MB 1 min ago Node 22 and our dependencies
CreateTemplate {"name": "my-app", "sandbox_id": "…", "description": "Node 22 and our dependencies"}
ListTemplates {"name": "my-app"}
Step 3: Inicia sandboxes desde ella
Indica la plantilla en CreateSandbox: "my-app" es su versión READY más reciente, "my-app@2" exactamente esa. El primer sandbox de una versión en un servidor la descarga, a unos 10 s por GiB; el servidor la conserva, y los siguientes se inician en unos 0,22 s.
preview = sandboxes.create_sandbox("my-app")
print(preview.sandbox_id, preview.template) # 8j37xshusqwdz8cs my-app@1
const preview = await sandboxes.createSandbox({ template: "my-app" });
console.log(preview.sandboxId, preview.template);
preview, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "my-app"})
if err != nil {
log.Fatal(err)
}
fmt.Println(preview.SandboxID, preview.Template)
let preview = sandboxes
.create_sandbox(CreateSandboxRequest { template: "my-app".into(), ..Default::default() })
.await?;
println!("{} {}", preview.sandbox_id, preview.template);
$ pethost sandbox new --template my-app
✓ Made sandbox ofvm8by6buvd4rkd: default, running, from my-app@2, in <1 s
port 5173: https://5173-ofvm8by6buvd4rkd.sbx1.sandboxes.pethost.network
ofvm8by6buvd4rkd
Next: pethost sandbox run ofvm8by6buvd4rkd -- <command> · pethost sandbox shell ofvm8by6buvd4rkd
CreateSandbox {"template": "my-app"}
El template de la respuesta nombra la versión exacta desde la que se inició, como my-app@1.
Qué conserva una plantilla
- Se conserva: cada archivo del disco del sandbox, entre ellos los paquetes, tu código y las imágenes y los contenedores de Docker; y los ajustes del sandbox, con los que empiezan sus sandboxes salvo que su creación diga otra cosa.
- No se conserva: la memoria y los procesos, así que un sandbox desde una plantilla empieza sin nada de lo que se ejecutaba; el historial de comandos y las conversaciones de los agentes de programación, sin los que empiezan sus sandboxes.
- Nuevo en cada sandbox: su propio id, hostname, machine-id y aleatoriedad del kernel.
Para copiar un sandbox con su memoria y sus procesos, tal como está en este segundo, haz mejor un fork: forks. Una plantilla es para muchos sandboxes durante días; un fork, para unas pocas copias ahora.
Versiones y tamaños
Cada guardado de un nombre es su siguiente versión. "my-app" siempre significa la READY más reciente, y la anterior mientras se guarda una nueva, así que guardar nunca rompe tus creaciones. Un nombre conserva 10 versiones; una versión FAILED no ocupa nada y desaparece al día siguiente. Un espacio de trabajo guarda una versión cada vez, y un sandbox conserva la versión desde la que se inició, incluso después de que elimines la plantilla.
Una versión READY tiene un min_size: el tamaño más pequeño en cuyo disco cabe lo que guardó. Sus sandboxes admiten cualquier tamaño a partir de ese. Una creación con un tamaño menor se rechaza, nombrando el que cabe.
Dónde se guarda, y cuánto cuesta
Una versión se reduce a lo que contiene, se comprime, se cifra con una clave propia y se guarda en almacenamiento de objetos en la UE, desde donde cualquier servidor puede iniciar sandboxes. Solo cuentan sus propios bytes, no la base que tiene debajo. Las plantillas no se facturan: tu plan limita lo que ocupan juntas las versiones del espacio de trabajo, 5 GiB con el plan de 20 US$ y 30 GiB con el de 100 US$ (Limits.template_gib; Workspace.template_bytes es lo que ocupan ahora). DeleteTemplate elimina todas las versiones de un nombre y libera el espacio al momento; los sandboxes hechos a partir de ella siguen ejecutándose, pausándose y reanudándose.
Nuestra plantilla: base
base es Ubuntu 24.04 con herramientas de build y git, Python 3, Node.js 22, Docker con Compose, Claude Code, Codex y OpenCode, y un escritorio con Google Chrome. La reconstruimos cada mes, y al momento ante un arreglo de seguridad de Chrome, del kernel o de un paquete. Template.base nombra la versión de base sobre la que se inician los sandboxes de una plantilla, con un hash de lo que contiene: una versión que guardas conserva la base sobre la que se inició su sandbox, así que tu plantilla no cambia sin que lo sepas.
No hay build desde un Dockerfile: ejecuta los pasos de tu Dockerfile en un sandbox, o docker build dentro de él, y guarda ese sandbox.
Cuando no funciona
RESOURCE_EXHAUSTEDconLimitReached,template_gib: las versiones del espacio de trabajo ocupan el espacio de su plan, u otra versión se está guardando. Elimina una plantilla antigua, o espera al guardado.LimitReached,template_versions: el nombre tiene 10 versiones. Guarda con un nombre nuevo, o elimina la plantilla y vuelve a guardar.- La versión está FAILED:
failure_messagedice por qué, como una versión cuyos bytes propios superaron el espacio que quedaba. Libera espacio y vuelve a guardar. INVALID_ARGUMENTque nombra un tamaño: el tamaño es menor que elmin_sizede la versión. Pide ese tamaño o uno mayor.- El primer sandbox de una versión nueva es lento: su servidor descargó la versión, a unos 10 s por GiB. Los siguientes ahí se inician en unos 0,22 s.
Preguntas
¿Cómo creo una plantilla de sandbox propia?
Prepara un sandbox como quieras los nuevos, y llama a CreateTemplate con un nombre y su id. Inicia los sandboxes nuevos con ese nombre.
¿Una plantilla conserva los procesos en ejecución?
No: solo archivos y ajustes. Para copiar un sandbox en ejecución con su memoria y sus procesos, haz un fork.
¿Se facturan las plantillas?
No. Tu plan limita cuántos GiB ocupan en almacenamiento de objetos las plantillas del espacio de trabajo.
¿Puedo crear una plantilla desde un Dockerfile?
No directamente: ejecuta los pasos del Dockerfile, o docker build, en un sandbox, y guarda el sandbox como plantilla.
¿Las imágenes de Docker se conservan en una plantilla?
Sí. Las imágenes y los contenedores de Docker están en el disco del sandbox, que la plantilla conserva.
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.