Arquitetura do OpenSandbox: Como as Peças se Encaixam Antes do Deploy
Por Fabio Douek
Ir para seção
- Visão Geral
- Arquitetura
- Conceitos
- O sandbox e os seus estados
- Os objetos do Kubernetes
- O modelo de configuração
- Egress em três camadas, e o Credential Vault
- O menu de isolamento
- O que roda onde no Kubernetes
- Configuração
- Passo 1: Ferramentas e o código complementar
- Passo 2: A config do servidor, e por que não o exemplo do pacote
- Passo 3: Inicie o servidor
- Testes
- Teste 1: Um primeiro sandbox pelo SDK Python
- Teste 2: O mesmo com a CLI osb
- Teste 3: Uma network policy deny-by-default
- O que as execuções locais mostraram
- Veredito
- Com o que você se compromete
- Para quem serve
Explica (TLDR) como se eu fosse...
Imagina uma caixa de areia no parquinho onde um robô ajudante pode cavar e construir sem fazer bagunça em nenhum outro lugar. Agora imagina que cada robô ganha a sua própria caixinha de areia, um adulto que a monta e depois arruma tudo, e um portão que decide quais partes do parquinho o robô pode visitar.
A parte esperta é que o portão guarda as chaves de verdade. O robô só carrega chaves de mentirinha, e quando ele chega a uma porta pela qual pode passar, o portão troca pela chave de verdade. Quando eu testei, o portão manteve uma porta fechada até eu dizer sim, e aí ela abriu na hora.
O OpenSandbox é uma plataforma sob licença Apache 2.0 para rodar código escrito por agentes de IA em sandboxes isolados, em infraestrutura que a própria organização opera. A Agentic AI Foundation, um directed fund da Linux Foundation, o anunciou como projeto em 22 de outubro de 2026, embora os seus maintainers e vários nomes de pacotes ainda remetam à Alibaba.
As questões de due diligence são maturidade e custódia. Não há linha de suporte de longo prazo nem API v1 estável, as releases recentes não são assinadas, apesar do que diz a documentação, e as credenciais de saída ficam em um proxy dentro do mesmo pod que o código não confiável. Trate o projeto como infraestrutura que o próprio time possui e audita.
A queixa principal é código escrito por um agente que precisa de um lugar seguro para rodar, com acesso à rede e API keys que ele não deveria conseguir roubar. O tratamento é em camadas: um container ou uma máquina virtual por sandbox, um sidecar de egress que filtra nomes e pacotes, e um vault que adiciona credenciais na saída.
A evidência aqui é um teste local da release 1.2.0 no Docker, em que uma policy deny-by-default bloqueou um host e o liberou depois de uma mudança ao vivo. Contraindicações: o gVisor não pode ser combinado com controle de egress, e a maior parte das novidades da release mira um perfil Firecracker que esta série não roda.
Existe uma tensão silenciosa em entregar um shell a um agente: você quer que ele faça trabalho de verdade, e se preocupa com o que ele consegue alcançar. O OpenSandbox tenta sustentar as duas coisas, dando a cada agente o seu próprio espaço enquanto as regras de rede e os segredos ficam nas mãos de outra pessoa.
O alívio é real, e a nova lição de casa também. Um time que o adota assume um servidor, um controller, sidecars e uma linha de releases planejada a cada duas semanas, sem suporte de longo prazo. O projeto agora está em um fundo da Linux Foundation, mas cerca de metade dos seus commits vem de contas ligadas a uma única empresa, e vale dizer isso em voz alta logo no início.
Pense no OpenSandbox como um conjunto de salas de ensaio reservadas uma por músico. O servidor de lifecycle é a recepção que faz as reservas, o execd é o técnico de som sentado em cada sala, e o sidecar de egress é a porta que decide quem pode sair para o corredor e quais corredores levam a algum lugar.
A sessão local manteve um bom andamento: cerca de quatro segundos para abrir uma sala depois que o equipamento esquentou, mais tempo para o primeiro take do dia. A parte interessante foi a porta. Um corredor ficou fechado até eu mudar a partitura no meio da sessão, e o take seguinte passou direto, sem contagem.
A história é ser dono da própria infraestrutura. O OpenSandbox permite que um time de plataforma rode sandboxes de agentes nas próprias máquinas, com um vault que mantém as API keys reais fora do sandbox. A Agentic AI Foundation, um directed fund da Linux Foundation, o anunciou como projeto em 22 de outubro de 2026.
O time to value em um laptop é curto: um arquivo de config com versões fixadas, um primeiro sandbox em cerca de quatro segundos depois de aquecido, e uma network policy deny-by-default funcionando na mesma sessão. O posicionamento honesto é para times dispostos a operar infraestrutura e acompanhar releases rápidas, não para times procurando um produto hospedado.
Visão Geral
Em 22 de outubro de 2026, na AGNTCon + MCPCon North America, em San Jose, a Agentic AI Foundation (AAIF) anunciou o OpenSandbox como um de seus projetos, contribuído pela Alibaba. A papelada veio dois dias antes: o charter técnico do projeto, adotado em 20 de outubro de 2026, o torna “OpenSandbox a Series of LF Projects, LLC” e nomeia a AAIF como “um directed fund da Linux Foundation”. Xiaobin Xu, Head of Development Infrastructure da Alibaba, deu o motivo no anúncio:
“Embora o OpenSandbox tenha sido criado na Alibaba, não queremos que o seu futuro seja definido por uma única empresa. Ao levar o projeto para a AAIF, estamos criando um caminho para que mais desenvolvedores e organizações ajudem a definir como os ambientes de sandbox funcionam em todo o ecossistema de agentes.”
O OpenSandbox é uma plataforma Apache 2.0 para rodar o código que agentes de IA escrevem: comandos de shell, arquivos, interpretadores de código, navegadores. Você pede um sandbox a um servidor de lifecycle, ele cria um no Docker ou no Kubernetes, e um pequeno daemon dentro do sandbox, o execd, executa o que você envia. A parte que mais me interessa é o lado da rede. Um sidecar de egress pode limitar um sandbox a uma allowlist deny-by-default, e o Credential Vault dele adiciona credenciais de API às requisições de saída, de modo que a ideia é o código no sandbox guardar apenas placeholders. Seja dono do sandbox e mantenha as chaves fora dele: esse é o ângulo desta série.
O código é público desde 17 de dezembro de 2025, quando o repository foi criado e a primeira release do execd recebeu uma tag. A release 1.2.0 saiu em 27 de outubro de 2026, e todas as imagens, packages e charts desta série estão fixados nela.
Este post, parte 1 de 6, é o mapa: como as peças se encaixam, os conceitos de que você precisa antes de fazer deploy de qualquer coisa, e uma execução local curta com o SDK Python, a CLI osb e uma network policy. A parte 2 instala o OpenSandbox no Amazon EKS 1.37, a parte 3 cobre o ciclo de vida do sandbox, os pools e o isolamento, a parte 4 o sidecar de egress e o Credential Vault, a parte 5 credenciais AWS assinadas no egress, e a parte 6 faz um stress test em dois nodes. Tudo em Configuração e Testes rodou no meu Mac arm64 em 31 de outubro de 2026, no Docker Desktop (Docker 29.2.1).
Arquitetura
A visão geral da arquitetura do projeto descreve o OpenSandbox como seis superfícies e três caminhos de tráfego. As superfícies são o que você instala ou chama. Os caminhos são o que você protege.
| Superfície | O que é | Onde roda |
|---|---|---|
| Cliente | SDKs para Python, JavaScript/TypeScript, Java/Kotlin, C#/.NET e Go; a CLI osb; um servidor MCP (opensandbox-mcp) | A sua aplicação, o seu laptop, o host do agente |
| Protocolo | Specs OpenAPI em specs/: a lifecycle API (caminho base /v1), a API do execd, a API de egress, diagnóstico | Contratos, não um processo |
| Control plane de lifecycle | Um servidor FastAPI: API keys, validação de requisições, resolução de endpoints, um proxy opcional, um pequeno store | Um processo no Docker, um Deployment no Kubernetes |
| Backends de runtime | Docker, ou Kubernetes por meio de um controller e três custom resources; opcionalmente, o Fast Sandbox para microVMs Firecracker | O seu host Docker ou o seu cluster |
| Data plane do sandbox | A sua imagem mais o execd na porta 44772 | Um container, ou um pod |
| Rede e segurança | Ingress gateway, sidecar de egress, Credential Vault, runtimes de container seguros | Um Deployment do gateway; um sidecar por sandbox |
O tráfego de lifecycle e o de execução vêm de qualquer cliente que você usar. O tráfego de saída começa dentro do sandbox. Os três caminhos, nas cores do diagrama:
- Lifecycle (âmbar). Create, list, pause, resume, renew e delete vão para o servidor. Ele valida a requisição e a repassa ao backend de runtime: no Docker, ele mesmo cria os containers; no Kubernetes, ele grava um custom resource e o controller faz o resto.
- Execução e serviço (azul). Comandos, arquivos, o terminal interativo (PTY) e a execução de código não passam pelo servidor. Um cliente pede ao servidor, uma única vez, o endpoint da porta 44772 e depois fala com o
execddiretamente (uma porta do host no Docker, um IP de pod no Kubernetes), pelo ingress gateway, ou pelo proxy do servidor em/sandboxes/{id}/proxy/{port}quando nenhum dos dois está acessível, caso em que o próprio servidor repassa a requisição aoexecd. - Saída (verde). Tráfego do sandbox para o mundo externo. Sem network policy, ele sai como o tráfego de qualquer container. Com uma, ele passa pelo próprio sidecar de egress do sandbox, que aplica a policy e pode injetar credenciais.
Vale conhecer duas regras do documento de arquitetura do servidor antes de fazer deploy de qualquer coisa: a API nunca fala diretamente com um runtime, e sandboxes nunca são linhas no banco de dados do servidor. No Kubernetes, os custom resources são a fonte da verdade; no Docker, são os containers e os seus labels. O store do servidor guarda apenas o que pertence ao servidor: os metadados de snapshots e o catálogo de templates do Fast Sandbox.
O Fast Sandbox é o ponto fora da curva. É uma plataforma separada (opensandbox-group/fast-sandbox) que roda microVMs Firecracker dentro de pods pré-aquecidos, e o servidor encaminha para ela quando uma requisição de criação informa um templateId. Esta série não o instala; o menu de isolamento abaixo lista o que ele exige.
Conceitos
Tudo nesta seção vem da leitura da documentação e do código-fonte na tag release-1.2.0. Eu rodo o caminho Docker em Configuração e Testes, mais abaixo; o lado Kubernetes roda no EKS nas partes 2 a 6.
O sandbox e os seus estados
Um sandbox é um ambiente isolado com um ID, uma imagem, limites de recursos e, normalmente, uma expiração. Na spec, a criação é assíncrona: o servidor pode responder enquanto o sandbox ainda está Pending, e os SDKs fazem polling até ele ficar Running. No Kubernetes, o servidor 1.2.0 só responde depois que o pod está rodando (a parte 3 verifica isso). A spec de lifecycle define oito estados:
Algumas regras que os nomes não contam:
resume()só funciona a partir dePaused. Um sandbox cujo workload terminou acaba emTerminated(exit code 0) ou emFailed(diferente de zero), e a resposta para os dois casos é um sandbox novo. O servidor nunca reinicia um sandbox silenciosamente. Um pod excluído é outra história: a parte 3, Teste 6, mostra o controller recriando o pod enquanto o sandbox continuaRunning.- No Kubernetes,
DELETEretorna 204 e o sandbox informaStoppingaté os seus pods sumirem, e depois 404. Essa é uma mudança da 1.2.0, assim como um BatchSandbox expirado informarTerminatedcom o motivoSANDBOX_EXPIRED, segundo as release notes; a parte 3 nunca flagrou esse estado no caminho até a exclusão. - Pausar no Kubernetes faz commit do filesystem raiz do sandbox em uma imagem em um registry OCI e exclui o pod. O resume o recria a partir dessa imagem, com o mesmo ID. Os arquivos voltam; a memória, os processos em execução e as entradas do Credential Vault, não (guia de pause e resume). A parte 3 mede isso.
Expiração e renovação. Quatro mecanismos decidem quanto tempo um sandbox vive:
| Mecanismo | O que faz | Limites |
|---|---|---|
timeout na criação | Define uma expiração absoluta, contada a partir da criação. Não é um timeout de inatividade, e reinícios do servidor ou do runtime não o zeram | No mínimo 60 s; limitado por max_sandbox_timeout_seconds quando o servidor define um (não definido por padrão; as configs de exemplo do pacote definem 86.400) |
renew-expiration | Define uma nova expiração absoluta | Pode encurtar, além de estender; não é limitado por max_sandbox_timeout_seconds |
| Renovação no acesso | O tráfego pelo proxy do servidor, ou eventos do gateway entregues pelo Redis, movem a expiração para max(now + extendSeconds, current expiry) | Opt-in: [renew_intent] no servidor e lifecycle.renewalPolicy.extendSeconds (300 a 86.400) no sandbox |
| Pausa por inatividade e despertar no acesso | Pausa um sandbox ocioso e o desperta na próxima requisição | Só no Fast Sandbox na 1.2.0 |
timeouté opcional na API: omita-o ou envienulle o sandbox nunca expira sozinho, embora providers do Kubernetes que não conseguem rodar workloads sem expiração possam rejeitar isso.- O SDK Python envia 10 minutos quando você não passa um timeout, e nenhuma expiração quando você passa
timeout=None. Os meus scripts definem 10 minutos explicitamente.
Os objetos do Kubernetes
No Kubernetes, o servidor nunca cria um pod. Ele cria custom resources, objetos de tipos novos que o projeto adiciona ao Kubernetes por meio de custom resource definitions (CRDs), no grupo sandbox.opensandbox.io/v1alpha1. Um controller manager com três reconcilers, control loops que mantêm os pods e as imagens de cada resource alinhados com a sua spec, os transforma em pods e imagens:
| Objeto | O que é | Campos que importam |
|---|---|---|
BatchSandbox (nome curto bsbx) | Um sandbox, ou um lote de sandboxes idênticos: um pod template ou uma referência a um Pool, uma expiração, uma flag de pausa, tasks opcionais | replicas, template ou poolRef, expireTime, pause, taskTemplate |
Pool | Pods aquecidos e prontos que um sandbox pode reivindicar em vez de esperar um cold start | template, capacitySpec (bufferMin, bufferMax, poolMin, poolMax), recycleStrategy (Delete, Restart ou Noop) |
SandboxSnapshot | Um commit do filesystem raiz de um sandbox, executado como um Job no node do sandbox e enviado a um registry OCI | sandboxName; fase de status Pending, Committing, Succeed ou Failed |
O chart base também instala, por padrão, quatro CRDs sandbox.fast.io para o Fast Sandbox, quer você o use ou não. Alguns detalhes que moldam as partes 2 e 3:
- Um
BatchSandboxtambém pode rodar tasks, comandos que o controller inicia dentro dos seus pods, e ele tem a sua própria lista de fases:Succeedsignifica “o pod está pronto”, não “a task terminou”. - A reciclagem do pool é um trade-off que você escolhe.
Delete, o padrão, exclui um pod usado;Noopentrega ao próximo sandbox os arquivos e os processos do anterior. Um sandbox tirado de um pool não aceitavolumesnem umanetworkPolicy, então regras de egress por requisição e pools não se misturam. - As configurações de snapshot (registry, credenciais de push, nomes de imagem) são flags do controller, não config do servidor. O Job de commit roda como UID 0, com o socket do containerd do node montado.
- Como o servidor guarda apenas registros de snapshots e templates, perder o banco de dados dele significa perder os metadados públicos de snapshots, não sandboxes.
O modelo de configuração
Toda configuração do servidor fica em um único arquivo TOML. Localmente, é ~/.sandbox.toml, a menos que --config ou SANDBOX_CONFIG_PATH digam o contrário. No Kubernetes, o chart do servidor renderiza um ConfigMap e o monta em /etc/opensandbox/config.toml.
O chart não mapeia values para configurações uma a uma. configToml é o arquivo inteiro como uma única string, e sobrescrevê-lo substitui tudo o que há nele, inclusive o namespace dos sandboxes. Em seguida, o chart acrescenta um bloco [ingress] que ele gera a partir dos values server.gateway.*, algumas configurações chegam como variáveis de ambiente para que os segredos fiquem fora do ConfigMap, e uma annotation checksum/config reinicia o pod sempre que o TOML muda. A referência de configuração tem todas as chaves; estas são as seções que esta série toca:
| Seção TOML | O que controla | Como é definida no Kubernetes |
|---|---|---|
[server] | Endereço de bind e porta, api_key, max_sandbox_timeout_seconds | configToml (porta 80 no chart); a chave vem de um Secret via server.env, como OPENSANDBOX_SERVER_API_KEY |
[runtime] | type (docker ou kubernetes), execd_image | configToml |
[docker] | Modo de rede, faixa de portas do host, publish_host, capabilities removidas, pids_limit | Só Docker |
[kubernetes] | Namespace dos sandboxes, arquivo de template do BatchSandbox, sandbox_create_timeout_seconds (60 por padrão), rate limits da API | configToml; um arquivo de template customizado via server.volumes e server.volumeMounts |
[ingress] | direct ou gateway, o endereço e o modo de roteamento do gateway, chaves de assinatura para os tokens de endpoint do gateway | Gerado a partir de server.gateway.* e acrescentado ao configToml; chaves de secureAccess.keys ou de um Secret existente |
[egress] | Imagem do sidecar, mode (dns ou dns+nft), disable_ipv6, requests e limits do sidecar | configToml |
[store] | Caminho do SQLite, ou PostgreSQL | configToml; o DSN via OPENSANDBOX_STORE_POSTGRESQL_DSN |
[secure_runtime] | runc, gVisor, Kata ou Kata com Firecracker, e a RuntimeClass a usar | configToml |
[tenants] | API keys multi-tenant a partir de um arquivo tenants.toml | configToml, mais o arquivo via server.volumes |
A imagem, as réplicas e os recursos do servidor são values comuns de Deployment, e as configurações de pause e resume pertencem ao chart do controller (controller.snapshot.*), não ao TOML.
Egress em três camadas, e o Credential Vault
O controle de egress é um container sidecar que compartilha o network namespace do sandbox. É o único container em execução no pod com a capability NET_ADMIN; o container do workload a tem removida, então o código no sandbox não consegue reescrever o próprio firewall. Se o sidecar não consegue instalar as suas regras na inicialização, ele encerra, em vez de rodar como um pass-through silencioso (arquitetura de egress).
O sidecar só existe quando a requisição de criação inclui uma networkPolicy. Sem policy, sem sidecar, e o tráfego de saída não é filtrado. Uma policy é uma defaultAction (allow ou deny, com deny como padrão) mais regras cujo alvo é um domínio, um wildcard (*.example.com casa com subdomínios, não com o apex), um IP ou um CIDR. As regras podem ser alteradas enquanto o sandbox roda. Cada uma das três camadas se apoia na anterior:
- Proxy DNS, sempre ligado. Todo o tráfego na porta 53 é redirecionado para um proxy DNS no sidecar, em
127.0.0.1:15353. Um nome negado recebeNXDOMAIN; um nome permitido é resolvido e os seus endereços são registrados. Sozinho, esse é o mododns, que só filtra nomes. Um processo que conecta diretamente a um IP não é barrado. - nftables, no modo
dns+nft. Um filtro de pacotes que descarta tudo o que não foi explicitamente permitido. Endereços aprendidos a partir de respostas DNS permitidas recebem um lease com prazo limitado, para que “permitido” não vire silenciosamente “permitido para sempre”. DNS over TLS (porta 853) é sempre descartado, e as regras com escopo de porta adicionadas na 1.2.0 precisam desse modo. - Proxy HTTPS transparente, opcional. Um listener do mitmproxy na porta 18081, para o qual as portas 80 e 443 são redirecionadas. Ele termina o TLS com uma CA que o sidecar gera, e o bootstrap do
execdinstala essa CA nos trust stores do sandbox e defineSSL_CERT_FILE,REQUESTS_CA_BUNDLEeNODE_EXTRA_CA_CERTS, para que os clientes mantenham a verificação de certificados ligada. O projeto chama essa camada de “experimental, mas utilizável em produção”.
O Credential Vault é construído sobre a terceira camada. Uma credencial é um nome e um valor. Um binding diz para onde ela vai (scheme, host, método, path) e como: bearer, basic, apiKey, customHeaders ou passthrough, mais substituições opcionais de placeholders no path, na query, nos headers ou no body. Os valores são write-only; ler o vault nunca os retorna. Aqui está uma requisição, do início ao fim:
- Um cliente confiável fora do sandbox grava credenciais e bindings na API do sidecar na porta 18080, autenticado com o token de egress daquele sandbox.
- O workload consulta o host. O proxy DNS só responde para nomes permitidos e coloca os endereços, com lease, nos allow sets do nftables.
- O workload conecta na porta 443 com o seu token placeholder. Uma regra de redirect envia a conexão para o proxy HTTPS, que termina o TLS com a CA do sidecar.
- O proxy lê o vault ativo por um Unix socket privado e escolhe o binding mais específico que corresponde ao scheme, ao host, à porta, ao método e ao path da requisição: um host exato vence um wildcard. Um vencedor: ele define o header. Um empate: a requisição é recusada, com um 403 quando o body é pequeno e totalmente conhecido, ou com a conexão derrubada quando o body é grande (acima de cerca de 1 MiB) ou chunked. Nenhuma correspondência: a requisição segue inalterada. Se o socket não responde, toda requisição interceptada falha em modo fail-closed.
- O proxy abre a sua própria conexão upstream, e o nftables fiscaliza essa conexão como qualquer outra.
- O host upstream recebe a credencial real. No caminho de volta, os headers de resposta que contêm um valor injetado são substituídos por
[REDACTED]. Os bodies de resposta, não.
O vault tem pré-requisitos rígidos: o modo dns+nft, uma network policy e credentialProxy.enabled na requisição de criação. A policy deve ser deny-by-default, com todos os hosts dos bindings permitidos; default-allow ainda funciona na 1.2.0, mas registra um aviso de segurança no log. O vault vive apenas na memória do sidecar, então no Kubernetes uma pausa o apaga e um cliente confiável precisa gravá-lo de novo depois do resume. E as credenciais reais ficam no sidecar, que está no mesmo pod que o código não confiável. A parte 4 cutuca tudo isso, incluindo uma issue, aberta em 7 de novembro de 2026, em que o binding é escolhido pelo header Host em vez do server name do TLS (#1758).
O menu de isolamento
Por padrão, um sandbox é um container comum sob runc, compartilhando o kernel do node. Runtimes de container seguros adicionam uma camada, e o OpenSandbox oferece suporte a quatro deles, mais o Fast Sandbox como plataforma separada:
| Runtime | [secure_runtime] type | O que os nodes precisam | Com egress e o vault |
|---|---|---|---|
| runc | "" (o padrão) | Nada extra | Funciona (o Teste 3 abaixo o roda no Docker) |
| gVisor | gvisor | runsc e containerd-shim-runsc-v1 em todo node, uma RuntimeClass | Rejeitado com HTTP 400 |
| Kata (QEMU ou Cloud Hypervisor) | kata | KVM: bare metal, ou virtualização aninhada que exponha /dev/kvm; kata-deploy para as RuntimeClasses | Suportado segundo a documentação; a parte 2 tenta |
| Kata com Firecracker | firecracker (só Kubernetes, RuntimeClass obrigatória) | KVM, como acima | Permitido pelo servidor; não testado nesta série |
| Fast Sandbox | Não é um tipo de runtime: escolhido por requisição com templateId | Uma instalação separada: KVM, um disco de estado XFS com reflink (o setup recusa um disco sem reflink; desligar o XFS faz voltar a cópias completas), um modelo de CPU por pool, cgroup v2, amd64 | Um processo de egress compartilhado pelos sandboxes de cada pod pré-aquecido; o vault sobrevive à pausa |
As estimativas do próprio projeto para o custo de inicialização são de cerca de 10 a 50 ms para o gVisor, 125 ms para Kata com Firecracker, 200 ms para Cloud Hypervisor e 500 ms para QEMU. Não medi nenhum deles aqui. Três regras decidem o que você consegue rodar de fato:
- Um perfil por processo do servidor. O runtime é config do servidor, não um campo da requisição, então uma requisição não pode escolher. Se você precisa de dois, roda duas releases do servidor. No Kubernetes, o servidor verifica na inicialização se a RuntimeClass existe e se recusa a iniciar se ela não existir.
- gVisor e egress não se misturam. A pilha de rede do gVisor não tem a tabela
natdo iptables, de que o redirect de DNS do sidecar precisa, então o servidor recusa a combinação quando a requisição chega. O gVisor também não consegue fazer o pause e resume do filesystem raiz. Quando você quer controle de egress ou o vault, o menu se resume a runc ou Kata. - Kata precisa de KVM. No EC2, isso costumava significar uma instância
.metal. Desde fevereiro de 2026, o EC2 oferece virtualização aninhada em instâncias virtuais, começando pelas C8i, M8i e R8i de 8ª geração, e desde 18 de junho de 2026 isso inclui M7i, C7i e R7i, que é o que os nodes desta série usam. A parte 2 verifica se existe/dev/kvme tenta um pod Kata nele; se o Kata roda bem aninhado ainda é uma questão em aberto neste ponto.
O que roda onde no Kubernetes
Um sandbox no Kubernetes é um pod com até três containers, montado pelo provider de BatchSandbox do servidor:
| Container | Tipo | O que faz | Privilégios |
|---|---|---|---|
execd-installer | Init container, de execd_image | Copia execd, bootstrap.sh e helpers para um emptyDir montado em /opt/opensandbox | privileged quando o sandbox tem uma network policy e disable_ipv6 está ligado (o padrão), para gravar o sysctl de IPv6 |
sandbox | Container principal, a sua imagem | Roda /opt/opensandbox/bootstrap.sh e depois o seu entrypoint; o bootstrap inicia o execd na 44772 e instala a CA do proxy quando há uma | NET_ADMIN removido quando há uma policy |
egress | Sidecar, só com uma networkPolicy | Proxy DNS, nftables, o proxy HTTPS opcional e o vault; API na 18080 | Adiciona NET_ADMIN |
Três configurações no nível do pod vêm do provider e do template padrão. automountServiceAccountToken: false, então o sandbox não guarda nenhum token da API do Kubernetes. restartPolicy: Never, o padrão da 1.2.0, porque um restart in-place apaga a camada gravável enquanto o sandbox continua parecendo saudável. E o tolerations: [{operator: Exists}] do template padrão de BatchSandbox, que deixa os pods de sandbox caírem em qualquer node com taint; a parte 2 troca esse template. Pelos Pod Security Standards, um init container privilegiado e um sidecar que adiciona NET_ADMIN significam que um namespace de sandboxes no nível baseline ou restricted rejeitaria sandboxes que têm network policy. Eu não testei isso.
No Docker, o mesmo sandbox é um ou dois containers: sandbox-<id> e, com uma policy, sandbox-egress-<id>. O container do sandbox entra no network namespace do sidecar, e o sidecar publica todas as portas do sandbox. O Teste 3 mostra isso.
Configuração
A parte 1 roda localmente: sem cluster, sem conta AWS, sem API keys. O objetivo é ver cada caminho do diagrama funcionando antes de a parte 2 adicionar o Kubernetes.
Passo 1: Ferramentas e o código complementar
Você precisa do Docker, do uv (ele instala o Python, o SDK e a CLI no primeiro uso) e do curl. As três imagens ocupam cerca de 1,1 GB em arm64.
git clone https://github.com/fabiodouek/my2centsai-blog-samples.git
cd my2centsai-blog-samples/opensandbox-architecture
| Arquivo | O que faz |
|---|---|
sandbox.toml | A config do servidor: o exemplo Docker do pacote com sete linhas alteradas |
common.py | Configurações de conexão (OSB_DOMAIN, OSB_API_KEY) e os helpers que os scripts Python compartilham |
00_server.sh | Mostra onde o exemplo do pacote está desatualizado, faz pull das imagens, inicia o servidor e espera o /health |
01_first_sandbox.py | SDK Python: cria um sandbox, roda comandos, grava e lê um arquivo, lê métricas, encerra o sandbox |
02_cli.sh | O mesmo pelo osb |
03_network_policy.py | Uma policy deny-by-default, um host permitido na criação e um segundo permitido enquanto o sandbox roda |
99_cleanup.sh | Encerra todos os sandboxes, para o servidor, remove containers que sobraram |
Passo 2: A config do servidor, e por que não o exemplo do pacote
O package do servidor consegue gravar a sua própria config de exemplo com opensandbox-server init-config <path> --example docker. Na 1.2.0, esse exemplo está desatualizado. O 00_server.sh grava uma cópia nova e mostra onde ela difere da config que eu distribuo:
Packaged example (opensandbox-server 1.2.0 init-config --example docker) vs ./sandbox.toml:
-execd_image = "opensandbox/execd:v1.1.0"
+execd_image = "opensandbox/execd:release-1.2.0"
-image = "opensandbox/egress:v1.1.7"
+image = "opensandbox/egress:release-1.2.0"
-mode = "dns"
+mode = "dns+nft"
(api_key, publish_host, [proxy] resolve_internal and [store] path differ too: local choices)
execd:v1.1.0 e egress:v1.1.7 são as últimas tags por componente, de agosto de 2026, antes de o projeto passar todos os componentes para uma única versão. As imagens 1.2.0 têm a tag release-1.2.0. E mode = "dns" só filtra nomes, o que também significa que o Credential Vault se recusa a ligar.
Sete linhas mudam em relação ao exemplo, e o arquivo distribuído mantém todos os comentários e as demais configurações do exemplo. Aqui estão as linhas alteradas, em contexto; as notas no fim das linhas são minhas e não estão no arquivo:
[server]
host = "127.0.0.1"
port = 8080
api_key = "local-dev-key" # was commented out; a throwaway local value
[proxy]
resolve_internal = false # the example's own advice for macOS
[runtime]
type = "docker"
execd_image = "opensandbox/execd:release-1.2.0"
[store]
type = "sqlite"
path = "./opensandbox.db" # next to the scripts, gitignored
[docker]
network_mode = "bridge"
publish_host = "127.0.0.1" # commented out in the example
[egress]
image = "opensandbox/egress:release-1.2.0"
mode = "dns+nft"
A chave importa porque, sem uma, o servidor não inicia sem supervisão: um api_key vazio exige YES digitado em um terminal em até 30 segundos, ou OPENSANDBOX_INSECURE_SERVER=YES.
publish_host. Com ele comentado, como no exemplo do pacote, o Docker publica as portas de todo sandbox em 0.0.0.0. O próprio comentário do exemplo diz o que está em jogo: "Defina um IP para manter o execd e as portas do sandbox fora das interfaces públicas". Em uma execução anterior, que não está no vídeo, o docker ps mostrou 0.0.0.0:53476->44772/tcp para um sandbox: a API de comandos do execd dele em todas as interfaces de rede do meu laptop. Com publish_host = "127.0.0.1", as mesmas portas ficaram vinculadas ao localhost e o SDK funcionou sem mudanças.
Passo 3: Inicie o servidor
./00_server.sh
O script roda o servidor com uvx opensandbox-server@1.2.0 --config ./sandbox.toml, grava o log em server.log e espera o health check:
image ready: opensandbox/execd:release-1.2.0
image ready: opensandbox/egress:release-1.2.0
image ready: python:3.12-slim
OpenSandbox server 1.2.0 ready at http://127.0.0.1:8080 (pid 28990, log: server.log)
Na execução gravada, com as imagens já baixadas, o script levou 3,3 segundos, incluindo o diff do exemplo. Em uma execução anterior, curl http://127.0.0.1:8080/health respondeu {"status":"healthy"}. Rodar o script de novo só informa que o servidor já está no ar.
Testes
Teste 1: Um primeiro sandbox pelo SDK Python
O núcleo do 01_first_sandbox.py, resumido. As configurações de conexão e o helper run(), que imprime um comando, a saída dele e o exit code, ficam em common.py:
sb = SandboxSync.create(
image=SandboxImageSpec(IMAGE), # python:3.12-slim
timeout=timedelta(minutes=10),
connection_config=connection(), # 127.0.0.1:8080, the API key from sandbox.toml
)
try:
run(sb, "uname -a")
run(sb, "python3 --version")
sb.files.write_files([WriteEntry(path="/tmp/hello.txt", data=text, mode=644)])
assert sb.files.read_file("/tmp/hello.txt") == text, "file content changed on the way"
m = sb.get_metrics()
finally:
sb.kill()
uv run python 01_first_sandbox.py
created sandbox 924dd5cb-9254-4c7c-91b7-51a1a98e5b5b from python:3.12-slim in 14.2 s
state: Running
$ uname -a
Linux 425375d63b8a 6.12.76-linuxkit #1 SMP Fri Mar 6 10:10:19 UTC 2026 aarch64 GNU/Linux
exit code: 0
$ python3 --version
Python 3.12.16
exit code: 0
file round trip: ok
metrics: 1 CPU, 0.0% used, 9 of 2048 MiB memory
killed
O create foi para o servidor: o caminho de lifecycle. Tudo depois dele foi direto para o execd, em uma porta de localhost que o Docker publicou para o sandbox: o caminho de execução, com o servidor fora do circuito. A linha do kernel é a VM do Docker Desktop: sob runc, o sandbox compartilha o kernel do host, que é o isolamento que você recebe por padrão. A API exige um tamanho em todo create; quando você não passa um, o SDK Python pede 1 CPU e 2 GiB.
Os 14,2 segundos são do primeiro create depois de iniciar o servidor, e não são típicos; a tabela de resultados abaixo mostra a variação. O log do servidor explica o motivo. No primeiro create, o servidor lê os arquivos da imagem do execd para a memória uma única vez (execd cache read archive, 8.278 ms nesta execução), e em todo create ele copia esse archive para o novo container. Essa cópia levou 4.660 ms neste primeiro create e 3.253 e 3.117 ms nos dois seguintes (o sandbox da CLI e o sandbox com policy, mais abaixo): a maior parte de um create aquecido. Criar o container em si levou de 26 a 35 ms, e iniciá-lo, de 75 a 136 ms.
Uma coisa que eu não esperava: todo create do SDK também envia um POST /v1/metrics/events com a duração do create para o servidor de lifecycle. Ele vai para o seu próprio servidor, não para terceiros, e OPENSANDBOX_DISABLE_METRICS=1 desliga isso.
Teste 2: O mesmo com a CLI osb
O 02_cli.sh usa o mesmo servidor pela CLI, guardando as configurações dela em um osb.toml local (o script passa --config ./osb.toml em toda chamada):
osb config init
osb config set connection.domain 127.0.0.1:8080
osb config set connection.api_key local-dev-key
osb sandbox create --image python:3.12-slim --timeout 10m -o json
osb sandbox list
osb command run "$id" -- ls /
osb file write "$id" /tmp/hello.txt --content "hello from the cli"
osb file cat "$id" /tmp/hello.txt
osb sandbox metrics "$id"
osb sandbox kill "$id"
A saída gravada do ./02_cli.sh, em um bloco recolhido. Cortei a listagem do ls / com ... e deixei de fora os spinners de progresso que o osb desenha enquanto lista e encerra sandboxes, que o terminal apaga:
Saída da CLI
$ osb config set connection.domain 127.0.0.1:8080
✅ Set connection.domain = 127.0.0.1:8080
$ osb config set connection.api_key local-dev-key
✅ Set connection.api_key = local-dev-key
$ osb sandbox create --image python:3.12-slim --timeout 10m -o json
{
"id": "48254b07-8157-4a97-be9e-a49872f5e14c",
"status": "created",
"timeout": "0:10:00",
"image": "python:3.12-slim"
}
$ osb sandbox list
Sandboxes
╭──────────────────────────────────────┬───────────┬──────────────────┬─────────────────────────┬──────────────────────────╮
│ ID │ STATUS │ IMAGE │ CREATED_AT │ EXPIRES_AT │
├──────────────────────────────────────┼───────────┼──────────────────┼─────────────────────────┼──────────────────────────┤
│ 48254b07-8157-4a97-be9e-a49872f5e14c │ ● Running │ python:3.12-slim │ 2026-10-31T18:41:13.40… │ 2026-10-31T18:51:13.409… │
╰──────────────────────────────────────┴───────────┴──────────────────┴─────────────────────────┴──────────────────────────╯
$ osb command run 48254b07-8157-4a97-be9e-a49872f5e14c -- ls /
bin
boot
dev
...
usr
var
$ osb file write 48254b07-8157-4a97-be9e-a49872f5e14c /tmp/hello.txt --content "hello from the cli"
✅ Written: /tmp/hello.txt
$ osb file cat 48254b07-8157-4a97-be9e-a49872f5e14c /tmp/hello.txt
hello from the cli
$ osb sandbox metrics 48254b07-8157-4a97-be9e-a49872f5e14c
Sandbox Metrics
╭─────────────────────┬─────────────────────╮
│ Key │ Value │
├─────────────────────┼─────────────────────┤
│ cpu_count │ 1.0 │
├─────────────────────┼─────────────────────┤
│ cpu_used_percentage │ 0.05333413371682062 │
├─────────────────────┼─────────────────────┤
│ memory_total_in_mib │ 2048.0 │
├─────────────────────┼─────────────────────┤
│ memory_used_in_mib │ 7.1171875 │
├─────────────────────┼─────────────────────┤
│ timestamp │ 1793472078882 │
╰─────────────────────┴─────────────────────╯
$ osb sandbox kill 48254b07-8157-4a97-be9e-a49872f5e14c
Sandboxes
╭──────────────────────────────────────┬────────────────────╮
│ SANDBOX_ID │ STATUS │
├──────────────────────────────────────┼────────────────────┤
│ 48254b07-8157-4a97-be9e-a49872f5e14c │ deletion_requested │
╰──────────────────────────────────────┴────────────────────╯
$ osb sandbox list
ℹ️ No sandboxes found.
Mesmo servidor, mesmos resultados, e alguns hábitos da CLI que vale conhecer:
osb config setfalha até queosb config inittenha criado o arquivo.createinforma"status": "created"enquantolistjá mostra o sandbox rodando.listretorna 20 linhas por página por padrão, e o JSON dele usa snake_case (has_next_page) onde a REST API usa camelCase (hasNextPage).- Um comando que falha dentro do sandbox faz o
osbsair com 1; uma chave errada imprime um painel de quatro linhas comINVALID_API_KEYe um request ID.
A CLI também cobre snapshots, templates, policy de egress, o Credential Vault, diagnóstico e um terminal interativo (osb terminal, novo na 1.2.0). Ela não tem comandos para pools.
Teste 3: Uma network policy deny-by-default
O 03_network_policy.py cria um sandbox que pode acessar o pypi.org e nada mais, testa dois hosts e depois libera o segundo enquanto o sandbox roda (resumido; o script define os hosts em constantes):
sb = SandboxSync.create(
image=SandboxImageSpec(IMAGE),
timeout=timedelta(minutes=10),
network_policy=NetworkPolicy(
defaultAction="deny",
egress=[NetworkRule(action="allow", target="pypi.org")],
),
connection_config=connection(),
)
check(sb, "pypi.org", "200")
check(sb, "github.com", "blocked")
sb.patch_egress_rules([NetworkRule(action="allow", target="github.com")])
check(sb, "github.com", "200")
A python:3.12-slim não tem curl, e com o egress negado nada pode ser instalado, então o script grava um pequeno probe em Python dentro do sandbox e o roda para cada host. Ele sai com 1 se alguma resposta for diferente da esperada.
created sandbox d9b9e966-c139-462f-9c1e-7aa49bd88312 in 5.1 s
policy before: default deny; allow pypi.org
pypi.org: 200
github.com: blocked
policy after: default deny; allow github.com, allow pypi.org
github.com: 200
killed
As três verificações bateram. Algumas coisas que a execução mostrou:
- O sidecar adiciona um container, e algum tempo de create (veja a tabela). No host passaram a existir dois containers,
sandbox-<id>esandbox-egress-<id>, e o container do sandbox rodava no network namespace do sidecar (NetworkMode container:<sidecar>). Em uma execução anterior, odocker psmostrou o sidecar carregando todas as portas publicadas: as portas de container 8080, 18080 e 44772, cada uma em uma porta aleatória de localhost. - Um host bloqueado parece uma falha de DNS. Dentro do sandbox, um nome negado falha do mesmo jeito que um domínio inexistente, com
socket.gaierror: [Errno -2] Name or service not known(o erro que uma execução anterior imprimiu; o vídeo mostra apenasblocked), e não como uma conexão recusada: a camada de DNS responde primeiro, e o nftables pegaria qualquer coisa que se conectasse diretamente a um IP. - Um patch é imediato e faz merge. O
patch_egress_rulesadicionou a regra no topo da lista, deixou odefault denyintocado, e a requisição seguinte já passou. O patch também não passou pelo servidor de lifecycle: o SDK o enviou direto para a API do sidecar na porta 18080, a mesma API que o Credential Vault usa.
O que as execuções locais mostraram
A coluna do meio é a execução do vídeo. A coluna da direita é a variação em todas as execuções que fiz neste Mac em 31 de outubro de 2026, incluindo execuções anteriores que não estão no vídeo.
| Etapa | Na execução do vídeo | Todas as execuções |
|---|---|---|
| Início do servidor, imagens já baixadas | 3,3 s | 2,1 a 6,2 s (quatro execuções), incluindo o diff do exemplo |
| Primeiro create depois de iniciar o servidor | 14,2 s | 12,5 a 15,4 s (sete inícios) |
| Create posterior, sem policy | 4,0 s pelo osb na tela, incluindo a inicialização da própria CLI | 3,5 a 4,1 s com o SDK, uma execução em 5,4 s (execuções anteriores); 4,0 a 4,8 s pelo osb (três takes) |
| Create com uma policy de egress | 5,1 s | 5,0 a 5,4 s |
| Kill pelo SDK, sem sidecar | 0,44 s | 0,25 a 0,44 s |
| Kill pelo SDK, com sidecar | 0,89 s | 0,86 a 1,0 s (três takes) |
| Tamanho padrão do sandbox (SDK Python) | 1 CPU, 2 GiB; 9 MiB em uso em repouso (7 MiB no sandbox da CLI) | 1 CPU, 2 GiB; 6 a 9 MiB em uso em repouso |
Host permitido (pypi.org) | 200, 0,45 s depois da linha anterior | 0,44 a 0,53 s |
| Host bloqueado antes do patch, e depois | Falha 0,25 s depois da linha anterior, e então 200 | 0,25 a 0,27 s |
Imagens, como o docker images as informa em arm64 | não mostrado | execd 185 MB, egress 573 MB, python:3.12-slim 384 MB (uma execução anterior) |
Mais uma coisa que a execução me ensinou: parar o servidor não para os sandboxes. Quando matei o processo do servidor, os containers dos sandboxes continuaram rodando. Por isso, o script de cleanup encerra todos os sandboxes pela API antes de parar o servidor e depois remove qualquer container que ainda tenha um label opensandbox.io/id ou opensandbox.io/egress-sidecar-for:
./99_cleanup.sh
Veredito
A arquitetura se sustenta melhor do que eu esperava para um projeto tão jovem. Uma única lifecycle API fica sobre o Docker e o Kubernetes, as suas imagens não precisam de nada adicional porque a plataforma injeta o execd quando cria um sandbox, e o sidecar de egress transforma “este sandbox consegue acessar a internet” em uma policy que você pode ler e mudar em runtime. Localmente, todos os testes passaram depois que fixei as versões na config. O exemplo do pacote apontando para imagens anteriores à 1.2.0 foi a minha primeira amostra de quão rápido o projeto se move, e do quanto essa velocidade custa.
Com o que você se compromete
| Aspecto | OpenSandbox 1.2.0 em 31 de outubro de 2026 |
|---|---|
| Governança | Anunciado como projeto da AAIF em 22 de outubro de 2026; charter do LF Projects adotado em 20 de outubro de 2026 |
| Quem desenvolve | 175 contribuidores. Contas com Alibaba no campo de empresa ou de e-mail do GitHub escreveram 56% de todos os commits e 48% nas últimas 13 semanas; um maintainer escreveu cerca de 36% de todos os commits e cerca de 40% nas últimas 13 semanas. Os quatro maintainers do projeto têm Alibaba no campo de empresa ou de e-mail |
| Ritmo | Cerca de 123 commits por semana nas últimas 13 semanas; tempo mediano para fechar uma issue, 3 dias |
| Nomes de pacotes | npm @alibaba-group/opensandbox, Maven com.alibaba.opensandbox, NuGet Alibaba.OpenSandbox, módulo Go github.com/alibaba/OpenSandbox/... (#1134, aberta). Os nomes no PyPI são neutros |
| Releases | Uma versão para todas as imagens, charts e SDKs. A política é uma nova linha a cada duas semanas, com apenas a mais recente suportada e sem LTS; da 1.1.0 à 1.2.0 foram 36 dias. Os Helm charts não são publicados: você os renderiza a partir da tag do git |
| Estabilidade da API | Paths /v1, CRDs v1alpha1, e uma API v1 estável listada no roadmap como “não planejada no momento” |
| Cadeia de suprimentos | A documentação diz que as releases são assinadas e atestadas; 1.1.0, 1.1.1 e 1.2.0 não são (#2463, aberta). Nenhum security advisory publicado. OpenSSF Best Practices Silver |
| Kubernetes | Suporte da v1.21 à v1.34, segundo o BOM da release (a bill of materials que fixa todas as imagens e packages de uma release). O CI roda apenas clusters kind: 1.22.4 a 1.34.2 para os testes end-to-end do controller, 1.30.4 para os jobs com a stack mais completa. Nenhuma cloud gerenciada. Esta série roda o EKS 1.37 |
| Onde caem as novidades da 1.2.0 | Principalmente no perfil Fast Sandbox (Firecracker): pausa automática e despertar no acesso, um vault que sobrevive à pausa, uma CA de proxy fixada. O caminho BatchSandbox ganhou regras de egress com escopo de porta e correções |
| Comunidade | GitHub: 590 issues de 211 autores. Três submissões no Hacker News, nenhuma com comentário. Discord e DingTalk não podem ser pesquisados de fora |
| Evidência de adoção | Autodeclarada: 25 comentários na issue “Who is using OpenSandbox” (#143), cerca de 85% deles da China |
O que eu teria em mente antes de construir em cima dele:
- O caminho padrão do Kubernetes fica atrás do caminho de microVM. No BatchSandbox, você tem pause e resume manuais, um vault que é apagado a cada pausa e nenhuma pausa automática por inatividade. O Fast Sandbox tem tudo isso, atrás de uma instalação separada (veja o menu de isolamento). Esta série fica no BatchSandbox.
- O egress estreita o menu de isolamento para runc ou Kata, e o Kata precisa de KVM (veja o menu de isolamento).
- Os padrões foram escritos para outro setup. Sete referências de imagem nos charts apontam para o registry da Alibaba na China, o gateway que a documentação chama de obrigatório vem desligado no umbrella chart, e o exemplo Docker do pacote está desatualizado. A parte 2 é, em grande parte, sobre a distância entre os padrões e o EKS.
- As chaves ficam fora do sandbox, não fora do pod. O sidecar do vault compartilha o pod com o código em que você não confia; as partes 4 e 5 testam o quanto isso importa.
- Fixe tudo. Uma única versão umbrella, uma nova linha planejada a cada duas semanas e apenas a mais recente suportada significam que você ou atualiza no ritmo do projeto, ou aceita rodar algo sem suporte.
Para quem serve
O OpenSandbox serve para um time de plataforma que quer rodar sandboxes de agentes em infraestrutura que já possui, com network policy e credenciais sob o seu próprio controle, e que se sente confortável tratando as issues do GitHub como canal de suporte. Os conceitos são limpos o bastante para que o investimento se mantenha mesmo com o projeto em movimento.
Ele ainda não serve para quem precisa de uma linha de suporte de longo prazo, de releases assinadas para uma revisão de compliance ou de um contrato de API estável, nem para quem quer as principais novidades da 1.2.0 sem rodar Firecracker em nodes KVM dedicados. A parte 2 leva tudo o que está acima para o Amazon EKS 1.37 e descobre onde os padrões quebram.