segunda-feira, 16 de novembro de 2026 Edição nº 240
Buscar
Avaliação · Infraestrutura · 33 min de leitura

Arquitetura do OpenShell: Como as Peças se Encaixam Antes do Deploy

Por Fabio Douek

Ir para seção
Explica (TLDR) como se eu fosse...
O que é isso?

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.

GitHub Veja o código-fonte aqui: openshell-architecture

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.”

CLIENTES openshell CLI TUI (term) Python · Go · TS SDKs gRPC via mTLS ou OIDC GATEWAY (CONTROL PLANE) API · banco (SQLite/PG) PKI · JWTs policies · providers advisor · análise de risco COMPUTE DRIVER (UM POR GATEWAY) Docker · Podman Kubernetes pelo controller do Agent Sandbox VM (libkrun) experimental, opt-in 1 SANDBOX = 2 UNIDADES DE COMPUTAÇÃO SUPERVISOR (CONFIÁVEL) policy engine (OPA) terminação TLS · CA por sandbox regras L7 (REST, GraphQL, MCP) resolução de credenciais · SigV4 abre toda conexão upstream real WORKLOAD (NÃO CONFIÁVEL) seu agente + processos filhos runtime do sandbox (PID 1) broker seccomp · Landlock sem rede própria sem credenciais reais UPSTREAM APIs repos de pacote só hosts permitidos cria sessão (exec, SSH, logs) relay do broker lifecycle sessão (supervisor conecta para fora) saída
OpenShell 0.1.6: o gateway é o control plane; cada sandbox é um supervisor confiável mais um workload não confiável, e toda conexão de saída é feita pelo supervisor.

Três caminhos de tráfego passam por esta imagem, e ajuda mantê-los separados.

  1. 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 Sandbox e 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.
  2. 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 que openshell sandbox exec passa pelo gateway mesmo no seu próprio laptop.
  3. 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:

Provisioning Ready Error Stopping Stopped Starting Completed Deleting Suspending · Suspendedsó na API; sem driver na 0.1.6
Fases do sandbox na 0.1.6. Um processo principal que termina com 0 acaba em Completed; um exit diferente de zero acaba em Error. Reinícios e paradas mantêm o sandbox e o seu workspace; cada execução recebe uma nova geração com tokens novos.

Algumas coisas me surpreenderam:

  • Stop e start, sim; suspend, não. openshell sandbox stop mantém o sandbox e o seu workspace, e start o traz de volta com uma nova geração. suspend e resume existem na CLI (“retain its memory state”), mas no meu gateway Docker o suspend retornou “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-keep deleta 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ão never) 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çãoAplicada porMuda em runtime?
filesystem_policy (caminhos somente leitura e de leitura e escrita)Landlock no workloadNão. Travada na criação; recrie o sandbox
landlock (compatibility: best_effort ou requisito obrigatório)LandlockNão
process (usuário, grupo)o runtime do sandboxNão
network_policies (endpoints, binários, regras L7)o supervisorSim, ao vivo
providers (anexados com --provider, não fazem parte do YAML)o supervisorSim, 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 audit como padrão, não enforce. Um endpoint marcado com protocol: rest e access: read-only registra um POST e o deixa passar, a menos que você também defina enforcement: 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.

WORKLOAD 1curl api.github.com Authorization: Bearer openshell:resolve:env:… 2broker seccomp intercepta connect() + DNS binário: /usr/bin/curl SUPERVISOR 3policy: curl pode acessar api.github.com:443? 4termina TLS (CA por sandbox) Host ≠ endpoint → 403 request_authority_mismatch regras L7: método, caminho (audit ou enforce) placeholder → token real vinculado a este endpoint outro host permitido → 403 credential_endpoint_mismatch 5conexão TLS real, token real UPSTREAM api.github.com vê o token real um canal mTLS
Uma requisição de saída com uma credencial. O placeholder vira o token real apenas dentro do supervisor, e apenas para o endpoint ao qual o provider está vinculado.

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 Host nomeia outro host é recusada com request_authority_mismatch.
  • O vínculo é por endpoint, não por binário. Qualquer binário que a policy deixe acessar api.github.com pode 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 ou aws_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. Um policy set ou policy update comum 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

DriverComo um sandbox rodaIsolamento do hostObservações
DockerContainer de workload com network=none mais um container de supervisorKernel compartilhado; Landlock e seccompO que eu uso neste post
PodmanMesmo formato do DockerKernel compartilhado; Landlock e seccompBom para rootless
KubernetesPod de workload mais Pod de supervisor por sandboxKernel 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
VMmicroVM libkrun (QEMU só para GPU passthrough)Kernel guest separadoMarcado 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.

GATEWAY StatefulSet openshell SQLite em um PVC porta 8080 (gRPC, mTLS) AGENT SANDBOX CONTROLLER observa os CRs Sandbox cria o Pod do workload e o seu PVC UM SANDBOX (9 OBJETOS) Pod do supervisor os-supervisor-<id> egress aberto + Service na :5500 Pod do workload egress: nenhum, exceto TCP 5500 ao seu supervisor PVC de 2 GiB em /sandbox também criados custom resource Sandbox dois Services NetworkPolicy por sandbox dois Secrets de bootstrap PVC do workspace por namespace: três NetworkPolicies: duas cercas, ingress SSH UPSTREAM hosts permitidos
Um sandbox no Kubernetes. A NetworkPolicy é uma cerca externa atrás do broker dentro do workload, que é o mecanismo principal. Essa cerca só existe se o CNI do cluster aplicar NetworkPolicy.

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 resolve releases/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.6 retorna HTTP 404, e :0.1.6 retorna 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 python3 foi recusado em um host que o curl conseguia 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/15 que 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.org virou 198.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 --wait retornou 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 via push é 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:

ÁreaO que eu encontrei
GovernançaCNCF Sandbox desde a votação de 2026-09-26; onboarding ainda aberto; repo, registry, documentação e endpoint de telemetria ainda da NVIDIA
Quem desenvolve821 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 releasesReleases 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çaSeis 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 suprimentosOs 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 mudarTelemetria ligada; regras L7 em audit; modo de rede host do supervisor no Docker Desktop
KubernetesTestado 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.

Comments