cloudflare/sandbox-stable

SDK de Sandbox — paquete estable

Entornos Linux aislados en Cloudflare Containers, impulsados desde Workers.

Prefiere la documentación principal de Sandbox y los tipos estables instalados antes que la memoria. Este skill es una puerta de enlace, un contrato y un mapa de recuperación, no un manual completo.

Esta línea es el paquete npm estable actual. La documentación principal de Sandbox lo describe. Las aplicaciones existentes pueden quedarse aquí y seguir desplegándose.

Recomendamos nuevos proyectos en @cloudflare/sandbox@next con sandbox-next. Cuando puedas, planifica una migración con sandbox-migrate-to-next para estar listo cuando 1.0 se convierta en la versión estable. No fuerces ese cambio a menos que el usuario lo solicite.

1. Puerta de enlace — confirma la línea del paquete

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

Verificación	Debe coincidir con
Dependencia npm	Por defecto @cloudflare/sandbox (no @next / etiquetas de vista previa)
Imagen del contenedor	Imagen estable correspondiente (no cloudflare/sandbox:next)

Si encuentras…	Acción
@cloudflare/sandbox@next o una imagen next	Detente. Carga sandbox-next.
El usuario quiere migrar a 1.0 / @next	Detente. Carga sandbox-migrate-to-next. No apliques a medias APIs de vista previa en un paquete estable.
Solo limpiar APIs estables obsoletas	Quédate aquí; usa la guía de desaprobación 2026. Eso no es una migración a @next.

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

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

2. Contrato — no negociables

• await sandbox.exec(command) recibe una cadena de comando y se resuelve cuando el comando finaliza, con stdout / stderr / exitCode almacenados en búfer (y campos relacionados).
• El trabajo de larga duración y streaming utiliza las APIs de comando estables (startProcess, execStream y ayudantes relacionados), no el modelo de un solo manejador de @next. Abre la documentación de Comandos; no inventes manejadores output() de @next en estable.
• Las Sesiones pueden preservar el directorio de trabajo y el entorno entre comandos (sesión por defecto / enableDefaultSession, createSession). Consulta la documentación de Sesiones cuando el estado deba persistir entre llamadas.
• Las terminales de navegador interactivas suelen usar sandbox.terminal(request) y ayudantes de sesión/xterm en estable, no createTerminal de vista previa a menos que el paquete sea @next.
• Prefiere el transporte RPC al usar túneles o streaming grande/binario. Los transportes HTTP/WebSocket están obsoletos (guía de limpieza más abajo).
• Archivos, montajes, puertos, túneles, copias de seguridad, ciclo de vida e intérprete: usa la documentación principal para las firmas; confía en los tipos estables instalados.
• Configuración no secreta en el entorno del sandbox; credenciales en vivo en el Worker. Usa manejadores de salida cuando los procesos llamen a APIs externas.
• Los nombres de host de vista previa en producción necesitan DNS comodín en un dominio personalizado cuando se usen esos patrones de URL.
• No apliques las APIs de argv/process.output() de @next mientras la dependencia siga siendo estable.
• El bridge auto-desplegado permanece en el paquete e imagen estables. Bridge

Forma mínima:

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

export { Sandbox };

const sandbox = getSandbox(env.Sandbox, "user-123");
const result = await sandbox.exec('python3 -c "print(2 + 2)"');
// result.stdout, result.exitCode, result.success

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

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

Necesitas…	Abre
Orientarte	Visión general de Sandbox
Primer Worker, plantilla, Docker	Comienza
exec, streaming, procesos en segundo plano	API de Comandos · Ejecutar comandos · Procesos en segundo plano · Salida en streaming
Sesiones / estado del shell entre comandos	Concepto de Sesiones · API de Sesiones
Opciones de getSandbox, sleep, destruir	API de Ciclo de Vida · Opciones de Sandbox
Variables de entorno	Variables de entorno
Archivos	API de Archivos · Gestionar archivos · Vigilancia de archivos
Buckets / montajes	API de Almacenamiento · Montar buckets
Copias de seguridad	API de Copias de Seguridad · Copia de seguridad y restauración
Puertos, URLs de vista previa, exponer	API de Puertos · Exponer servicios
Túneles	API de Túneles
Proxy / conexiones Workers	Solicitudes proxy · Conexiones Workers
Terminal de navegador / PTY	API de Terminal · Concepto de Terminal · Terminales de navegador
Intérprete de código	API de Intérprete · Ejecución de código
Git en el sandbox	Flujos de trabajo Git
Secretos / salida	Tráfico de salida
WebSockets	Conexiones WebSocket
Docker-en-Docker	Docker en Docker
Despliegue en producción	Despliegue en producción
Concepto de Contenedores	Contenedores
Índice de guías	Guías
Índice de APIs	Referencia de API
APIs obsoletas permaneciendo en estable	Guía de desaprobación 2026
Bridge auto-desplegado	Bridge · API HTTP de Bridge
Ejemplos (estable/main)	ejemplos en GitHub
Trabajo nuevo en vista previa 1.0	sandbox-next · Vista previa 1.0
Migrar aplicación existente a @next	sandbox-migrate-to-next · Migrar

Limpieza de APIs obsoletas (permanece en estable)

Actualiza el paquete y la imagen correspondiente primero, luego sigue la guía. Búsqueda típica:

rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'

Este camino no te cambia a @next.

4. Antes de enviar

• Paquete Worker e imagen de contenedor en la misma línea estable
• Verificación de tipos contra los tipos estables instalados
• Sin secretos en vivo en el entorno del sandbox
• Si usas transportes/ayudantes obsoletos, finaliza o haz seguimiento de la limpieza de desaprobación 2026
• Cuando el equipo esté listo para 1.0, usa sandbox-migrate-to-next — no fuerces el cambio sin que te lo pidan