Arquitetura do OpenShell: Como as Peças se Encaixam Antes do Deploy
Por Fabio Douek
Ir para seção
- Visão Geral
- Arquitetura
- Conceitos
- Duas unidades de computação, um protocolo
- Fases e gerações
- Camadas de policy: o que fica travado e o que muda ao vivo
- Egress e credenciais: uma requisição
- Providers, o prover e o advisor
- Drivers e o menu de isolamento
- O que roda onde no Kubernetes
- Configuração
- Passo 1: Remova a 0.0.x primeiro
- Passo 2: Fixe a versão e desligue a telemetria
- Passo 3: Corrija o modo de rede do Docker Desktop
- Passo 4: Uma imagem de workload que não roda como root
- Testes
- Teste 1: Um primeiro sandbox pela CLI
- Teste 2: O mesmo pelo SDK Python
- Teste 3: Bloqueio por padrão, por binário, alterado ao vivo
- Veredito
Explica (TLDR) como se eu fosse...
Imagina que o seu robô ajudante trabalha em uma sala de brinquedos sem portas para o lado de fora. Quando ele precisa de alguma coisa lá de fora, ele passa um bilhete por baixo da parede para um adulto, que confere uma lista de lugares permitidos e só vai buscar se esse lugar estiver na lista.
O adulto também guarda as chaves da casa no próprio bolso. O robô só ganha uma chave de mentirinha, então um robô espertinho não consegue simplesmente sair por aí com as chaves de verdade. A lista pode mudar enquanto o robô continua brincando.
O OpenShell é um runtime sob licença Apache 2.0, originalmente da NVIDIA e aceito como projeto CNCF Sandbox em 2026-09-26, que confina agentes de IA e mantém as credenciais fora do código que as usa. O repository, o registry e a documentação ainda estão sob controle da NVIDIA enquanto o onboarding é concluído.
Para fins de due diligence: a telemetria vem ligada por padrão e precisa ser desligada explicitamente, as imagens de container não são assinadas e seis vulnerabilidades corrigidas em abril foram divulgadas em agosto. A evidência aqui é uma avaliação local, não uma auditoria.
A condição em tratamento é um agente que consegue alcançar tudo o que o seu host alcança. O OpenShell separa o paciente da farmácia: o agente roda em um workload sem rede e sem segredos, e um supervisor confiável ao lado dele decide cada requisição de saída com base em uma policy escrita.
A evidência é inicial, mas concreta: em uma execução local, um binário que não estava nomeado na policy foi recusado mesmo para um host permitido. Os efeitos colaterais incluem requisitos mais rígidos para as imagens, como não usar o usuário root, e uma mudança de policy que levou dez segundos para ser aplicada no modo padrão.
Existe um tipo particular de ansiedade em deixar um agente rodar sozinho com acesso real: você quer a ajuda e teme aquele único comando que vai para onde não deveria. O OpenShell transforma essa preocupação em uma lista escrita que alguém de fora do agente faz cumprir.
O alívio vem acompanhado de trabalho novo. Alguém precisa ser dono da lista, revisar o que o agente pede para adicionar e aceitar que dizer não agora fica visível nos logs. Essa responsabilidade compartilhada é o verdadeiro passo de adoção, mais do que a instalação.
Pense no OpenShell como um técnico de som entre a banda e o PA. O agente toca à vontade na sua cabine, mas nada chega ao salão a menos que o técnico abra aquele canal, e é o técnico quem tem os únicos cabos de patch que carregam credenciais reais.
O andamento é constante, não instantâneo: um canal novo aberto no meio do show levou dez segundos para entrar na minha execução, porque a cabine confere as novas deixas em um compasso fixo. Dá para mudar para deixas sob demanda, mas o groove padrão é um compasso de dez segundos.
O pitch é controle sem reescrever o agente. Envolva qualquer agente em um sandbox do OpenShell e ele ganha rede com bloqueio por padrão, credenciais apenas como placeholders e uma linha de auditoria para cada conexão recusada.
O time to value em um Mac foi uma instalação curta mais dois ajustes de configuração, e os sandboxes iniciaram em cerca de dois segundos. A história para contar aos compradores é a de um projeto neutro na CNCF com um modelo real de aplicação das regras, sendo franco sobre os padrões que ainda precisam ser mudados.
Visão Geral
Em 2026-09-26, o Technical Oversight Committee da CNCF votou pela aceitação do OpenShell como projeto Sandbox (cncf/sandbox#522), com 72,73% dos votantes com voto vinculante a favor e nenhum contra. O acordo de contribuição foi registrado como assinado em 2026-10-02. O onboarding (#535) ainda estava aberto quando escrevi isto, e o repository, o registry de imagens e a documentação ainda ficam sob a NVIDIA.
O OpenShell é um runtime Apache 2.0 para rodar agentes de IA sob regras que eles não podem alterar. Você envolve um agente existente, ou qualquer processo, em um sandbox. Um componente confiável fora desse sandbox decide quais arquivos ele pode tocar, quais hosts ele pode acessar, com qual binário, e quais credenciais são anexadas na saída. O próprio agente recebe placeholders, não API keys reais; o supervisor coloca o valor real no lugar quando a requisição sai. O projeto se define como “o runtime seguro e privado para agentes de IA autônomos”.
Estou usando a release v0.1.6 (2026-10-27). O repository foi criado em fevereiro de 2026, ficou público em meados de março e publicou 115 tags v0.0.x entre março e agosto. A versão 0.1.0 (2026-09-25) marca a saída do projeto do alpha, e mudou a arquitetura o suficiente para que instalações 0.0.x não possam ser atualizadas in place. Qualquer coisa escrita sobre o OpenShell antes de setembro pode descrever um design que não existe mais.
Este post, parte 1 de 6, explica como as peças se encaixam e as roda localmente em um Mac. O resto da série roda o OpenShell no Amazon EKS:
- Parte 2: instalação no EKS 1.37
- Parte 3: ciclo de vida e isolamento do sandbox
- Parte 4: policy e egress
- Parte 5: credenciais AWS assinadas no supervisor
- Parte 6: stress test em dois nodes
Sandboxes com GPU ficam fora do escopo de toda a série. O OpenShell oferece suporte a eles, mas nada aqui usa GPU.
Arquitetura
O OpenShell tem quatro partes com as quais você interage, e uma fronteira que importa mais do que todo o resto.
- Clientes: a CLI
openshell, uma UI de terminal (openshell term) e SDKs para Python, Go e TypeScript. Todos falam gRPC com o gateway. - O gateway é o control plane. Ele armazena sandboxes, policies, providers (conjuntos de credenciais) e o histórico deles, emite certificados e tokens, e pede a um compute driver que crie os sandboxes de fato. Existem drivers para Docker, Podman, Kubernetes e microVMs.
- O supervisor é a metade confiável de cada sandbox. Ele guarda a policy, termina o TLS das conexões de saída do sandbox, aplica regras no nível HTTP, resolve credenciais e abre toda conexão upstream real.
- O workload é a metade não confiável: o seu agente e tudo o que ele inicia, mais um pequeno runtime do OpenShell que roda como PID 1 dentro dele. Esse runtime é código do OpenShell que a documentação chama de confiável, mas ele roda dentro da fronteira do workload junto com o agente e não toma nenhuma decisão de policy.
Desde a 0.1.0, essas duas metades são unidades de computação separadas: dois containers no Docker ou no Podman, dois Pods no Kubernetes. Na 0.0.x, o supervisor rodava dentro do container do agente. O RFC 0012 explica a mudança em uma frase: “o privilégio necessário para construir essa fronteira fica ao lado do código que ela confina.”
Três caminhos de tráfego passam por esta imagem, e ajuda mantê-los separados.
- Ciclo de vida. A CLI pede ao gateway que crie um sandbox, e o gateway pede ao seu driver as duas unidades de computação. No Kubernetes, o driver cria um custom resource
Sandboxe um Pod de supervisor separado, e o controller do Agent Sandbox (um projeto de SIG do Kubernetes do qual o OpenShell depende) cria o Pod do workload a partir dele. - Sessão.
exec, SSH, transferência de arquivos e streaming de logs nunca abrem uma porta no sandbox. O supervisor conecta para fora, até o gateway, e mantém essa sessão aberta; o gateway retransmite o seu comando por ela. É por isso que um sandbox atrás de NAT ou de um firewall restritivo continua funcionando, e é por isso queopenshell sandbox execpassa pelo gateway mesmo no seu próprio laptop. - Saída. Quando o agente se conecta a qualquer lugar, a conexão nunca sai diretamente do workload. O workload não tem nenhum caminho de rede, exceto até o seu próprio supervisor. O runtime do OpenShell dentro dele intercepta a chamada
connect()e a consulta DNS, identifica qual binário as fez e entrega a requisição ao supervisor por um único canal HTTP/2 com autenticação mútua (o “OpenShell Sandbox Protocol”). O supervisor verifica a policy, termina o TLS se o endpoint exigir, aplica as regras HTTP e as credenciais, e faz ele mesmo a conexão real.
Conceitos
Duas unidades de computação, um protocolo
A divisão é a ideia central. O workload guarda o agente e o pequeno runtime do OpenShell, nada mais: nenhum token de sandbox, nenhuma chave de cliente TLS, nenhuma credencial, nenhuma chave privada de CA. Ele tem a chave pública do gateway para poder verificar o que lhe dizem. O supervisor guarda os privilégios e os segredos.
Dentro do workload, um broker de seccomp user notification intercepta aberturas de conexões TCP e consultas DNS. Para cada uma, ele lê o processo chamador em /proc e fixa o binário pelo seu SHA-256 no primeiro uso. A policy pode então dizer “curl pode acessar este host” em vez de “este container pode acessar este host”. Os sockets do agente ficam vinculados ao loopback dentro do workload, então não há outro lugar para onde eles possam ir.
Dois detalhes da página de arquitetura valem a pena conhecer antes de depurar qualquer coisa:
- Ele falha fechado: sem o seu supervisor, o agente não recebe nada, em vez de uma rede aberta. O workload não inicia o agente até o supervisor confirmar, e se a conexão do supervisor cair, o agente é congelado. Só o mesmo processo supervisor pode reconectar e retomá-lo, em até 30 segundos por padrão; caso contrário, o workload é parado (a parte 3 mostra isso no EKS). Um novo supervisor não pode assumir um sandbox em execução.
- Os tokens são por execução. O gateway emite um token de gateway e um token de sandbox vinculados a um sandbox e a uma “geração”: uma execução das unidades de computação do sandbox. Cada reinício, ou um stop seguido de start, inicia uma nova geração com tokens e certificados novos.
Uma armadilha da documentação: a página de boas práticas de segurança do OpenShell ainda descreve um network namespace com um par veth e um proxy HTTP CONNECT em 10.200.0.1. Esse é o design da 0.0.x. A página de arquitetura, os READMEs dos drivers e o código na tag v0.1.6 descrevem o modelo de broker acima, e foi isso que a minha execução local mostrou: as linhas de bloqueio se referem a conexões “transparent”, e o ambiente do workload não tem nenhuma variável de proxy.
Fases e gerações
Um sandbox passa por um pequeno conjunto de fases, definidas no protocolo:
Algumas coisas me surpreenderam:
- Stop e start, sim; suspend, não.
openshell sandbox stopmantém o sandbox e o seu workspace, estarto traz de volta com uma nova geração.suspenderesumeexistem na CLI (“retain its memory state”), mas no meu gateway Docker osuspendretornou “compute driver does not support sandbox suspend”. Nenhum driver embutido implementa isso na 0.1.6: o gateway verifica as capacidades do driver e recusa antes de o driver ser consultado, então Podman, Kubernetes e VM dão a mesma resposta (a parte 3 mostra isso no EKS). - Não existe timeout por ociosidade. Não encontrei nenhum TTL ou expiração automática na documentação nem no protocolo da 0.1.6.
--no-keepdeleta o sandbox quando o seu primeiro comando termina; em qualquer outro caso, ele roda até você deletá-lo. - Quem cuida dos reinícios é o gateway, não o container runtime.
--restart-policy never|on-failure|always(padrãonever) decide o que acontece quando o processo principal termina.
Camadas de policy: o que fica travado e o que muda ao vivo
Uma policy de sandbox é um único arquivo YAML com seções que se comportam de formas diferentes (gerenciar policies):
| Seção | Aplicada por | Muda em runtime? |
|---|---|---|
filesystem_policy (caminhos somente leitura e de leitura e escrita) | Landlock no workload | Não. Travada na criação; recrie o sandbox |
landlock (compatibility: best_effort ou requisito obrigatório) | Landlock | Não |
process (usuário, grupo) | o runtime do sandbox | Não |
network_policies (endpoints, binários, regras L7) | o supervisor | Sim, ao vivo |
providers (anexados com --provider, não fazem parte do YAML) | o supervisor | Sim, ao vivo |
As mudanças ao vivo chegam ao supervisor de uma de duas formas, definida pelo config_delivery_mode do gateway. O padrão é poll, e os supervisores fazem polling a cada 10 segundos. A versão 0.1.5 adicionou push, que envia a configuração pela sessão já existente do supervisor. No meu gateway local, no modo padrão, uma atualização de policy levou mais ou menos isso: na gravação, o --wait reportou a nova versão carregada 10,0 segundos depois que eu a submeti.
Mais duas regras que vale a pena conhecer cedo:
- Uma nova geração de policy fecha as conexões abertas sob a anterior. Isso inclui conexões keep-alive, túneis e streams longos. É a escolha segura, e ela surpreende agentes de longa duração.
- As regras HTTP têm
auditcomo padrão, nãoenforce. Um endpoint marcado comprotocol: resteaccess: read-onlyregistra um POST e o deixa passar, a menos que você também definaenforcement: enforce. A parte 4 testa isso.
Egress e credenciais: uma requisição
É nas credenciais que o design compensa. Você cria um provider no gateway (um conjunto nomeado de credenciais, como um token do GitHub) e o anexa a um sandbox. Dentro do sandbox, o agente vê variáveis de ambiente como GITHUB_TOKEN, mas os valores delas são placeholders opacos no formato openshell:resolve:env:.... O valor real existe apenas no gateway e no supervisor.
Três propriedades desse fluxo, lidas no código da 0.1.6 e documentadas em providers:
- O vínculo é por endpoint, não pelo header Host. O supervisor escolhe a credencial a partir do endpoint para o qual a conexão foi permitida (host, porta e path). Uma requisição cujo header
Hostnomeia outro host é recusada comrequest_authority_mismatch. - O vínculo é por endpoint, não por binário. Qualquer binário que a policy deixe acessar
api.github.compode ter o placeholder do GitHub resolvido. A policy decide quem chega ao host; o provider decide o que é anexado ali. - O supervisor resolve o destino por conta própria. Ele se conecta a endereços que ele mesmo resolveu e fixou, nunca ao que o resolver do próprio sandbox afirma. Endereços de loopback e link-local (
169.254.0.0/16, que inclui os endpoints de metadados de cloud) são sempre bloqueados, diga a policy o que disser, e as portas do control plane do Kubernetes (2379, 2380, 6443, 10250, 10255) são bloqueadas para endpoints de host exato e de IP.
Para a AWS, há um passo além da substituição: o supervisor pode reassinar requisições com SigV4, e o próprio gateway pode emitir credenciais STS. A parte 5 trata disso.
Providers, o prover e o advisor
- Providers vêm de profiles. Desde a 0.1.0, o gateway não vem com nenhum embutido. Você importa um profile (GitHub, AWS, Anthropic e outros ficam em
providers/) e depois cria um provider a partir dele. As credenciais podem ser estáticas ou renovadas pelo provider: fluxos OAuth2, service accounts do Google ouaws_sts_assume_role. - O prover codifica as policies para o solver Z3 e responde a uma pergunta: uma policy candidata permite algo que uma policy de fronteira não permite? Ele roda como uma CLI independente,
openshell-prover(a fórmula do Homebrew o instala), o que se encaixa bem em CI. O próprio gateway só roda uma análise de risco nas propostas do advisor, a feature que permite a um agente propor uma mudança de policy para um humano aprovar. Umpolicy setoupolicy updatecomum não roda nenhum prover. E o prover verifica a policy, não a aplicação dela. A documentação do prover diz isso diretamente: passar na verificação “não significa que a policy seja tão restrita quanto poderia ser, que seja segura para uma tarefa específica, nem que um sandbox em execução a aplique.”
Drivers e o menu de isolamento
| Driver | Como um sandbox roda | Isolamento do host | Observações |
|---|---|---|---|
| Docker | Container de workload com network=none mais um container de supervisor | Kernel compartilhado; Landlock e seccomp | O que eu uso neste post |
| Podman | Mesmo formato do Docker | Kernel compartilhado; Landlock e seccomp | Bom para rootless |
| Kubernetes | Pod de workload mais Pod de supervisor por sandbox | Kernel do node compartilhado, ou uma RuntimeClass baseada em VM por sandbox (na parte 2, um sandbox 0.1.6 sob Kata falhou) | Precisa do controller Agent Sandbox e de um CNI que aplique NetworkPolicy |
| VM | microVM libkrun (QEMU só para GPU passthrough) | Kernel guest separado | Marcado como experimental no seu README; nunca escolhido automaticamente |
Sem uma configuração explícita, o gateway escolhe Kubernetes, depois Podman, depois Docker. Toda opção precisa de um kernel recente: Landlock ABI 3 ou mais nova (Linux 6.2+) e seccomp user notification. O runtime do sandbox verifica esses recursos na inicialização e se recusa a rodar se estiverem faltando. User namespaces são um extra opt-in no Kubernetes.
O que roda onde no Kubernetes
As partes 2 a 6 se passam aqui, então vale a pena ver esse formato uma vez.
Todo Pod do OpenShell (gateway, supervisor, workload) roda como não root, com todas as capabilities removidas e o perfil seccomp runtime-default: nenhum container privilegiado, nenhum host path. O custo é a densidade. Cada sandbox são dois Pods e um volume baseado em EBS, o que faz diferença em dois nodes (parte 6).
Configuração
A parte 1 roda o OpenShell no meu Mac (Apple Silicon, Docker Desktop com 10 CPUs) com o gateway instalado pelo Homebrew e o driver Docker. O diretório complementar tem cinco scripts e três arquivos de configuração.
Passo 1: Remova a 0.0.x primeiro
Meu Mac já tinha o OpenShell 0.0.63, de junho, com dois sandboxes. As notas de upgrade da 0.1.0 são diretas: “Instalações locais do OpenShell 0.0.x não podem ser atualizadas in place.” Eu deletei os sandboxes e depois desinstalei:
openshell sandbox delete <each sandbox>
brew services stop nvidia/openshell/openshell
brew uninstall nvidia/openshell/openshell
rm -rf "$(brew --prefix)/var/openshell"
O próprio instalador só protege upgrades a partir de versões anteriores à 0.0.37, então ele teria tentado atualizar a 0.0.63 in place. O 00_gateway.sh, em vez disso, se recusa e imprime os passos.
Passo 2: Fixe a versão e desligue a telemetria
O 00_gateway.sh instala com o script oficial, com a versão fixada:
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/v0.1.6/install.sh \
| OPENSHELL_VERSION=v0.1.6 sh
Duas armadilhas ao fixar a versão, ambas impressas pelo script:
- Sem
OPENSHELL_VERSION, o instalador resolvereleases/latest. No dia em que rodei, isso era a v0.1.6, mas sai uma release nova na maioria das terças-feiras. - As tags de release têm um
v; as tags de imagem de container não têm.ghcr.io/nvidia/openshell/gateway:v0.1.6retorna HTTP 404, e:0.1.6retorna 200. Valores do Helm e mirrors de imagens precisam da segunda forma.
A telemetria vem ligada por padrão. O controle em runtime é uma variável de ambiente no gateway, OPENSHELL_TELEMETRY_ENABLED=false, que o gateway repassa a todo supervisor; o server.telemetryEnabled do Helm chart define a mesma variável, e builds a partir do código-fonte podem compilar sem a telemetria (telemetria). No macOS, o wrapper do serviço Homebrew carrega ~/.config/openshell/gateway.env antes de iniciar o gateway, então o script grava o opt-out ali antes do primeiro start e depois verifica o processo em execução:
ps eww -p "$(pgrep -f bin/openshell-gateway | head -1)" | tr ' ' '\n' | grep OPENSHELL_TELEMETRY
# OPENSHELL_TELEMETRY_ENABLED=false
Passo 3: Corrija o modo de rede do Docker Desktop
Meu primeiro sandbox falhou com:
ControlSupervisorStartFailed: Docker supervisor exited before becoming ready
… Startup configuration fetch failed after 5 attempts: failed to connect to OpenShell server
O driver Docker inicia cada container de supervisor em modo de rede host por padrão e o aponta para 127.0.0.1:17670. No Docker Desktop para Mac, “host” é a VM do Docker, a menos que a configuração de host networking do Docker Desktop esteja ligada, e não estava. O outro modo, bridge, chega ao gateway por host.docker.internal, que já consta no certificado do gateway. Uma configuração em ~/.config/openshell/gateway.toml resolveu:
[openshell]
version = 2
[openshell.drivers.docker]
supervisor_network_mode = "bridge"
Passo 4: Uma imagem de workload que não roda como root
O OpenShell 0.1.x usa por padrão nvcr.io/nvidia/base/ubuntu:24.04, um Ubuntu mínimo sem nenhum agente instalado, então eu fiz o build de uma imagem pequena com curl, python3, git e jq, fixada no digest da base (a tag 24.04 muda). Meu primeiro build deixou o USER root como estava, e o sandbox foi recusado antes de iniciar:
IdentityResolutionFailed: descriptor error: workload identity must not contain UID or GID zero
A correção é uma linha no final do Dockerfile:
USER 1000:1000
Testes
Cada teste é um script no diretório complementar, gravado enquanto rodava para o vídeo. A imagem já estava em cache, então os tempos medem o OpenShell, não um pull.
Teste 1: Um primeiro sandbox pela CLI
O 01_first_sandbox.sh cria um sandbox, inspeciona o sandbox, roda dois comandos, envia um arquivo e o baixa de volta, lê os logs e o deleta.
openshell sandbox create --name first --from openshell-workload:0.1.6 --detach
openshell sandbox exec first -- uname -a
openshell sandbox exec first -- id
openshell sandbox upload first ./README.md /sandbox/
openshell sandbox download first /sandbox/README.md /tmp/out/
openshell logs first -n 15
openshell sandbox delete first
Do create até Ready levou 2,5 segundos. O kernel era o do Docker Desktop (6.12.76-linuxkit … aarch64), a identidade era uid=1000(ubuntu), e o arquivo voltou byte a byte. O openshell sandbox get mostra as partes do modelo descritas acima: a política de reinício (never), um ID de geração de runtime, o backend de isolamento (openshell-sandbox), uma condição Ready (motivo DependenciesReady, mensagem “Supervisor session connected”) e a policy efetiva.
Saída gravada do 01_first_sandbox.sh (resumida)
$ openshell sandbox create --name first --from openshell-workload:0.1.6 --detach
✓ Sandbox allocated (0s)
✓ Image already present (0s)
create to Ready: 2.5 s
$ openshell sandbox list
NAME CREATED PHASE
first 2026-10-31 21:07:06 Ready
$ openshell sandbox exec first -- uname -a
Linux 353948387e06 6.12.76-linuxkit #1 SMP Fri Mar 6 10:10:19 UTC 2026 aarch64 aarch64 aarch64 GNU/Linux
$ openshell sandbox exec first -- id
uid=1000(ubuntu) gid=1000(ubuntu) groups=1000(ubuntu),4(adm),20(dialout),…
$ openshell sandbox upload first ./README.md /sandbox/
✓ Upload complete: /sandbox/README.md
upload round trip: ok
$ openshell logs first -n 15
[sandbox] [OCSF ] [ocsf] CONFIG:LOADED [INFO] Acknowledged initial policy revision as loaded [version:1] …
[gateway] [INFO ] [openshell_server::supervisor_session] supervisor session: relay opened successfully
[gateway] [INFO ] [openshell_server::grpc::sandbox] ExecSandbox (relay): command started
Os logs mostram o caminho da sessão: todo exec é um relay pela sessão do supervisor, não uma conexão para dentro do container.
Teste 2: O mesmo pelo SDK Python
O 02_sdk.py faz o ciclo de vida em código, usando o registro do gateway local feito pela CLI (openshell) e o seu bundle mTLS:
from openshell import SandboxClient
with SandboxClient.from_active_cluster(cluster="openshell") as c:
ref = c.create(workspace="default", name="sdk-demo",
spec={"template": {"image": "openshell-workload:0.1.6"}})
c.wait_ready("sdk-demo", workspace="default", timeout_seconds=300)
result = c.exec("sdk-demo", ["python3", "--version"], workspace="default")
deletion = c.delete("sdk-demo", workspace="default")
c.wait_deleted("sdk-demo", workspace="default", expected_sandbox_id=deletion.sandbox_id)
Ele foi de Provisioning para Ready em 1,8 segundo e imprimiu Python 3.12.3 e Ubuntu 24.04.5 LTS. Dois pontos ainda mal acabados: o SDK retorna a fase como um número de enum cru e não reexporta o enum (o script lê os nomes do módulo protobuf gerado), e o classifier do pacote ainda diz “Alpha”. Com o gateway parado, os scripts de teste da CLI e do SDK imprimem uma linha e saem:
OpenShell gateway not reachable: run ./00_gateway.sh first
Teste 3: Bloqueio por padrão, por binário, alterado ao vivo
O policies/curl-only.yaml tem uma única regra de rede:
network_policies:
pypi:
name: pypi-curl-only
endpoints:
- host: pypi.org
port: 443
binaries:
- { path: /usr/bin/curl }
O 03_network_policy.sh cria um sandbox com ela, tenta três requisições, adiciona um host ao vivo e lê as linhas de bloqueio:
pypi.org (curl): 200
pypi.org (python3): denied
httpbin.org (curl): denied
$ openshell policy update netdemo --add-endpoint httpbin.org:443 --binary /usr/bin/curl --wait
✓ Policy version 2 submitted (hash: 0e14d8f0560b)
✓ Policy version 2 loaded (active version: 2)
httpbin.org (curl): 200 after the update (10.5 s)
As linhas de log dizem exatamente por que cada requisição falhou, e nomeiam o binário real por trás do symlink python3:
DENIED /usr/bin/python3.12(0) -> pypi.org:443 [reason:transparent_tcp_policy_denied]
DENIED httpbin.org [reason:policy_dns_ineligible]
DENIED /usr/bin/curl(0) -> httpbin.org:443 [reason:transparent_tcp_policy_denied]
Três observações:
- O binário importa, não só o host. O
python3foi recusado em um host que ocurlconseguia acessar. No OpenShell, uma allowlist é uma lista de pares de binário e destino. - O DNS também é mediado. Os nomes resolvem para endereços sintéticos em
198.18.0.0/15que só o supervisor mapeia para os reais. Um nome fora da policy é sinalizado na consulta (policy_dns_ineligible), mas ainda recebe um endereço sintético, então a conexão que vem depois pode ser negada com o nome do binário nela:httpbin.orgvirou198.18.0.3, e a linha de bloqueio nomeia/usr/bin/curl. - A maior parte dos 10,5 segundos é o polling. Nos timestamps da gravação, o
--waitretornou 10,0 segundos depois do submit, e a primeira requisição permitida teve sucesso meio segundo depois. Isso bate com o polling padrão de 10 segundos do supervisor, embora o atraso não seja fixo: a parte 4 mediu de 7,9 a 12,5 segundos no EKS. A entrega viapushé o ajuste a usar se um agente fica esperando mudanças de policy.
Minha primeira tentativa usou example.com como segundo host, e ele nunca resolveu, com o motivo policy_dns_upstream_nxdomain. No fim, a rede em que eu estava não resolve example.com de jeito nenhum, dentro ou fora do OpenShell. O código de motivo transformou isso em um diagnóstico de dois minutos.
Veredito
A arquitetura do OpenShell é a parte mais convincente dele. Dividir cada sandbox em um workload que não guarda nada e um supervisor que guarda tudo elimina toda uma classe de falhas: não há segredo no ambiente do agente para vazar (embora uma fraqueza conhecida da 0.1.6 ainda possa colocar a sessão AWS real ao alcance do agente; veja a parte 5), e não há socket que o agente possa abrir sem passar por uma decisão de policy com o nome do binário nela. A execução local confirma a metade de rede disso; ela não anexou nenhuma credencial. Os sandboxes iniciam em cerca de dois segundos, as linhas de bloqueio são específicas, e o modelo de policies (regras de filesystem travadas, regras de rede ao vivo) é fácil de entender.
Com o que você se compromete:
| Área | O que eu encontrei |
|---|---|
| Governança | CNCF Sandbox desde a votação de 2026-09-26; onboarding ainda aberto; repo, registry, documentação e endpoint de telemetria ainda da NVIDIA |
| Quem desenvolve | 821 commits na main nas 13 semanas até 2026-10-31, de 79 autores; pela minha estimativa, cerca de 68% ligados à NVIDIA e cerca de 17% à Red Hat; 10 de 13 maintainers da NVIDIA, 3 da Red Hat |
| Política de releases | Releases semanais às terças desde a v0.1.4; a política de estabilidade (RFC 0014) promete suporte N-1, mas ainda está em revisão, sem branch de manutenção por enquanto; a v0.1.6 saiu com uma dispensa do release captain para uma mudança incompatível no protobuf |
| Histórico de segurança | Seis CVEs, dois com CVSS 9,9, todos em versões até a 0.0.33; corrigidos na v0.0.34 em 2026-04-21 e divulgados em 2026-08-25 (boletim da NVIDIA). Nenhum security advisory no repository, então scanners de dependências não vão sinalizar versões antigas |
| Cadeia de suprimentos | Os binários de release e o wheel trazem attestations de proveniência do GitHub; as imagens de container têm SBOM e proveniência, mas nenhuma assinatura; o Helm chart não tem nada anexado |
| Padrões a mudar | Telemetria ligada; regras L7 em audit; modo de rede host do supervisor no Docker Desktop |
| Kubernetes | Testado no upstream apenas em kind e k3s. O EKS não aparece na matriz de suporte, e é para isso que servem as partes 2 a 6 |
Quem deveria olhar: times que querem agentes rodando sem supervisão com credenciais reais e querem as regras aplicadas fora do agente, em um formato que um revisor consiga ler. Quem deveria esperar: quem precisa hoje de suspend e resume, expiração por ociosidade ou imagens assinadas, ou quem não pode aceitar um trem de releases semanal cuja política de estabilidade ainda está em revisão e já foi dispensada uma vez.
A pergunta em aberto para o resto da série é se esse quadro limpo sobrevive a um cluster real: um CNI aplicando a cerca externa, dois Pods e um volume por sandbox em dois nodes, e credenciais AWS assinadas no supervisor. A parte 2 começa pela instalação.