cloudflare/sandbox-next

SDK de Sandbox — @next (vista previa 1.0)

Entornos Linux aislados en Cloudflare Containers, controlados desde Workers.

Prefiere la documentación de vista previa y los tipos @next instalados sobre la memoria. Las API cambian; esta habilidad es una puerta, un contrato y un mapa de recuperación, no un manual completo.

Recomendamos proyectos nuevos en esta línea. Las aplicaciones que aún usan el paquete por defecto deben usar sandbox-stable. Realiza la migración solo cuando se solicite, a través de sandbox-migrate-to-next.

1. Puerta — confirma la línea del paquete

Antes de escribir código, inspecciona la aplicación:

Verificación	Debe coincidir
Dependencia npm	@cloudflare/sandbox@next (u otra etiqueta de vista previa)
Imagen del contenedor	Misma línea (por ejemplo, cloudflare/sandbox:next, next-python)

Si encuentras…	Acción
@cloudflare/sandbox por defecto (sin @next)	Detente. Carga sandbox-stable. No apliques las API de esta habilidad.
El usuario desea migrar de estable a @next	Detente. Carga sandbox-migrate-to-next.
Solo un puente autodesplegado	El puente no está aún en la línea de vista previa 1.0. Mantén el puente en el paquete e imagen estables. Puente (estable)

Nunca mezclas un paquete de Worker @next con una imagen de contenedor estable (ni al revés).

Instalación de habilidades: Configuración del agente · cloudflare/skills

2. Contrato — no negociables

• sandbox.exec(argv) toma una lista argv y se resuelve cuando el proceso inicia. Devuelve un manejador, no un resultado de comando finalizado.
• Recopila resultados con métodos del manejador: output(), logs(), waitForExit(), waitForPort(), waitForLog(), kill(signal?).
• No hay shell implícito. La sintaxis de shell necesita un shell explícito, por ejemplo, ["/bin/bash", "-lc", script].
• Cada lanzamiento es independiente. Un cd/export en un exec no es visible para el siguiente. Pasa cwd y env por lanzamiento, o un script shell único.
• Los manejadores de proceso no tienen stdin. Uso interactivo → terminales (createTerminal + connect).
• La espera local timeout/AbortSignal cancela solo la espera. No mata el proceso. Usa kill o el timeout remoto de exec.
• getProcess/listProcesses/getTerminal/listTerminals no inician un contenedor; devuelven null/[] cuando no hay ninguno activo.
• Los IDs de proceso y terminal pertenecen al contenedor actual, no para siempre a un ID de sandbox. Para trabajo que debe sobrevivir a un reemplazo, almacena el trabajo completo (argv, cwd, env, estado de la aplicación), no solo un ID.
• Configuración no secreta solo en setEnvVars/lanzamiento env. Las credenciales en vivo se quedan en el Worker; usa manejadores de salida cuando el sandbox llame a API externas.
• No inventes API estables eliminadas (gitCheckout en core, finalización de exec con string, ejecución de sesión, sandbox.terminal(request)).
• No uses un bucle de reintento para cada error (consulta la documentación de Errores).

Forma mínima:

import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";

export { Sandbox };

const sandbox = getSandbox(env.Sandbox, "user-123");
const process = await sandbox.exec(["python3", "-c", "print(2 + 2)"]);
const result = await process.output({ encoding: "utf8" });
// result.stdout, result.exitCode

Documentación de API específica para tareas: references/api-quick-ref.md

Índice de ejemplos (rama next): references/examples.md

3. Recupera — abre la documentación para la tarea

Obtén la página antes de implementar. Los tipos @next instalados tienen prioridad sobre las suposiciones.

Necesitas…	Abre
Orientarte/elegir vista previa	Visión general de vista previa 1.0
Primer Worker, wrangler, Dockerfile	Empieza
exec, manejadores, preparación, durabilidad	Ejecución de procesos
Firmas de API de procesos	API de procesos
ID de Sandbox vs contenedor vs suspensión/destrucción	Ciclo de vida
cwd/env/setEnvVars	Entorno
PTY interactivo / terminal del navegador	Terminales · API de terminales
Intérprete de código Python/JS	Intérprete · API del intérprete
Modelo de extensiones	Extensiones
Clases de error y recuperación	Errores · API de errores
Fallos comunes	Solución de problemas
Centro de API	Referencia de API
Archivos, montajes, copias de seguridad, puertos, túneles, proxyToSandbox	Documentación principal para superficies compartidas (ignora sesión/transporte/sandbox.terminal solo estables): Archivos · Almacenamiento/montajes · Puertos · Túneles · Copias de seguridad · Tráfico saliente · Exponer servicios · Producción
Aplicaciones de ejemplo	ejemplos en next
Aún en paquete estable	sandbox-stable · Documentación principal de Sandbox
Migrar una aplicación estable existente	sandbox-migrate-to-next · Migrar

4. Antes de lanzar

• Lockfile y Dockerfile en la misma línea @next
• Verificación de tipos contra los tipos @next instalados
• Sin secretos en vivo en el entorno del sandbox
• Los nombres de host de vista previa en producción necesitan DNS comodín en un dominio personalizado cuando se usan esos patrones de URL