cloudflare/sandbox-stable

SDK Sandbox — pacote estável

Ambientes Linux isolados nos Containers Cloudflare, acionados a partir de Workers.

Prefira a documentação principal do Sandbox e os tipos estáveis instalados em vez da memória. Esta skill é um portal, um contrato e um mapa de recuperação — não um manual completo.

Esta linha é o pacote npm estável atual. A documentação principal do Sandbox o descreve. Aplicativos existentes podem permanecer aqui e continuar sendo publicados.

Recomendamos novos projetos em @cloudflare/sandbox@next com sandbox-next. Quando possível, planeje uma migração com sandbox-migrate-to-next para estar pronto quando a versão 1.0 se tornar o lançamento estável. Não force essa migração a menos que o usuário solicite.

1. Portal — confirme a linha do pacote

Antes de escrever código, inspecione o aplicativo:

Verificação	Deve corresponder
Dependência npm	@cloudflare/sandbox padrão (não tags @next / pré-visualização)
Imagem do container	Imagem estável correspondente (não cloudflare/sandbox:next)

Se você encontrar…	Ação
@cloudflare/sandbox@next ou uma imagem next	Pare. Carregue sandbox-next.
Usuário deseja migrar para 1.0 / @next	Pare. Carregue sandbox-migrate-to-next. Não aplique parcialmente APIs de pré-visualização em um pacote estável.
Apenas limpeza de APIs estáveis obsoletas	Fique aqui; use o guia de descontinuação 2026. Isso não é uma migração para @next.

Nunca misture um pacote Worker estável com uma imagem de container @next (ou o inverso).

Instalação de skills: Configuração do agente · cloudflare/skills

2. Contrato — inegociáveis

• await sandbox.exec(command) recebe uma string de comando e resolve quando o comando termina, com stdout / stderr / exitCode armazenados em buffer (e campos relacionados).
• Trabalhos de longa duração e streaming usam as APIs de comando estáveis (startProcess, execStream e auxiliares relacionados) — não o modelo de alça única do @next. Consulte a documentação de Comandos; não invente handles output() do @next no estável.
• Sessões podem preservar o diretório de trabalho e o ambiente entre comandos (sessão padrão / enableDefaultSession, createSession). Consulte a documentação de Sessões quando o estado precisar ser transferido entre chamadas.
• Terminais interativos do navegador geralmente usam sandbox.terminal(request) e auxiliares de sessão/xterm no estável — não createTerminal de pré-visualização, a menos que o pacote seja @next.
• Prefira transporte RPC ao usar túneis ou streaming grande/binário. Transportes HTTP/WebSocket estão obsoletos (guia de limpeza abaixo).
• Arquivos, montagens, portas, túneis, backups, ciclo de vida e interpretador: use a documentação principal para assinaturas; confie nos tipos estáveis instalados.
• Configuração não secreta no ambiente do sandbox; credenciais ao vivo no Worker. Use manipuladores de saída quando processos chamarem APIs externas.
• Nomes de host de pré-visualização de produção precisam de DNS curinga em um domínio personalizado ao usar esses padrões de URL.
• Não aplique APIs de argv/process.output() do @next enquanto a dependência ainda for estável.
• Bridge auto-implantado permanece no pacote e imagem estáveis. 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. Recupere — abra a documentação para a tarefa

Busque a página antes de implementar. Os tipos estáveis instalados têm precedência sobre suposições.

Você precisa…	Abra
Se orientar	Visão geral do Sandbox
Primeiro Worker, template, Docker	Comece por aqui
exec, streaming, processos em segundo plano	API de comandos · Executar comandos · Processos em segundo plano · Saída em streaming
Sessões / estado do shell entre comandos	Conceito de sessões · API de sessões
Opções getSandbox, sleep, destroy	API de ciclo de vida · Opções do Sandbox
Variáveis de ambiente	Variáveis de ambiente
Arquivos	API de arquivos · Gerenciar arquivos · Monitoramento de arquivos
Buckets / montagens	API de armazenamento · Montar buckets
Backups	API de backups · Backup e restauração
Portas, URLs de pré-visualização, expor	API de portas · Expor serviços
Túneis	API de túneis
Proxy / conexões Workers	Solicitações de proxy · Conexões Workers
Terminal do navegador / PTY	API de terminal · Conceito de terminal · Terminais do navegador
Interpretador de código	API de interpretador · Execução de código
Git no sandbox	Fluxos de trabalho com Git
Segredos / saída	Tráfego de saída
WebSockets	Conexões WebSocket
Docker-in-Docker	Docker no Docker
Implantação em produção	Implantação em produção
Conceito de containers	Containers
Índice de guias	Guias
Índice de API	Referência da API
APIs obsoletas permanecendo no estável	Guia de descontinuação 2026
Bridge auto-implantado	Bridge · API HTTP Bridge
Exemplos (estável/main)	exemplos no GitHub
Novo trabalho na pré-visualização 1.0	sandbox-next · Pré-visualização 1.0
Migrar aplicativo existente para @next	sandbox-migrate-to-next · Migrar

Limpeza de API obsoleta (permaneça no estável)

Atualize o pacote + imagem correspondente primeiro, depois siga o guia. Pesquisa típica:

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

Este caminho não o leva para @next.

4. Antes de publicar

• Pacote Worker e imagem de container na mesma linha estável
• Verificação de tipos com os tipos estáveis instalados
• Sem segredos ao vivo no ambiente do sandbox
• Se estiver usando transportes/auxiliares obsoletos, conclua ou acompanhe a limpeza do guia de descontinuação 2026
• Quando a equipe estiver pronta para 1.0, use sandbox-migrate-to-next — não force a migração sem solicitação