cloudflare/sandbox-next

SDK Sandbox — @next (pré-visualização 1.0)

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

Prefira documentos de pré-visualização e tipos @next instalados em vez da memória. As APIs mudam; esta skill é um portão, um contrato e um mapa de recuperação — não um manual completo.

Recomendamos novos projetos nesta linha. Aplicações ainda no pacote padrão usam sandbox-stable. Migre apenas quando solicitado, via sandbox-migrate-to-next.

1. Portão — confirme a linha do pacote

Antes de escrever código, inspecione a aplicação:

Verificação	Deve corresponder a
Dependência npm	@cloudflare/sandbox@next (ou outra tag de pré-visualização)
Imagem do container	Mesma linha (ex.: cloudflare/sandbox:next, next-python)

Se você encontrar…	Ação
@cloudflare/sandbox padrão (sem @next)	Pare. Carregue sandbox-stable. Não aplique as APIs desta skill.
Usuário quer migrar estável → @next	Pare. Carregue sandbox-migrate-to-next.
Bridge auto-implantado apenas	Bridge não está na linha de pré-visualização 1.0 ainda. Mantenha bridge no pacote e imagem estáveis. Bridge (estável)

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

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

2. Contrato — inegociáveis

• sandbox.exec(argv) recebe uma lista de argv e resolve quando o processo inicia. Retorna um handle, não um resultado de comando finalizado.
• Colete resultados com métodos do handle: output(), logs(), waitForExit(), waitForPort(), waitForLog(), kill(signal?).
• Sem shell implícito. Sintaxe de shell precisa de um shell explícito, ex.: ["/bin/bash", "-lc", script].
• Cada lançamento é independente. Um cd / export em um exec não é visível para o próximo. Passe cwd e env por lançamento, ou um único script de shell.
• Handles de processo não têm stdin. Uso interativo → terminais (createTerminal + connect).
• timeout / AbortSignal de espera local cancelam apenas a espera. Eles não matam o processo. Use kill ou o timeout remoto do exec.
• getProcess / listProcesses / getTerminal / listTerminals não iniciam um container; retornam null / [] quando nenhum está ativo.
• IDs de processo e terminal pertencem ao container atual, não para sempre a um ID de sandbox. Para trabalho que deve sobreviver a substituições, armazene o trabalho completo (argv, cwd, env, estado da aplicação)—não apenas um id.
• Configuração não secreta apenas em setEnvVars / env de lançamento. Credenciais ativas permanecem no Worker; use handlers de saída quando o sandbox chamar APIs externas.
• Não invente APIs estáveis removidas (gitCheckout no core, conclusão de exec como string, execução de sessão, sandbox.terminal(request)).
• Não use um único loop de repetição para todo erro (veja documentação de Erros).

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

Documentação da API específica para tarefas: referências/api-quick-ref.md

Índice de exemplos (branch next): referências/examples.md

3. Recupere — abra o documento para a tarefa

Busque a página antes de implementar. Os tipos @next instalados vencem palpites.

Você precisa…	Abra
Orientar / escolher pré-visualização	Visão geral da pré-visualização 1.0
Primeiro Worker, wrangler, Dockerfile	Comece
exec, handles, prontidão, durabilidade	Execução de processos
Assinaturas da API de processos	API de processos
ID do Sandbox vs container vs sono/destruir	Ciclo de vida
cwd / env / setEnvVars	Ambiente
PTY interativo / terminal do navegador	Terminais · API de terminais
Interpretador de código Python/JS	Interpretador · API do interpretador
Modelo de extensões	Extensões
Classes de erro e recuperação	Erros · API de erros
Falhas comuns	Solução de problemas
Central de API	Referência da API
Arquivos, montagens, backups, portas, túneis, proxyToSandbox	Documentos principais para superfícies compartilhadas (ignore sessão/transporte/sandbox.terminal apenas estáveis): Arquivos · Armazenamento / montagens · Portas · Túneis · Backups · Tráfego de saída · Expor serviços · Produção
Aplicações exemplo	exemplos no next
Ainda no pacote estável	sandbox-stable · Documentos principais do Sandbox
Migrando uma aplicação estável existente	sandbox-migrate-to-next · Migrar

4. Antes de publicar

• Lockfile e Dockerfile na mesma linha @next
• Verificação de tipos contra os tipos @next instalados
• Sem segredos ativos no ambiente do sandbox
• 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