Runtime em sandbox para agentes de IA autônomos com políticas YAML declarativas que impõem restrições de filesystem, rede e processos, além de injeção de credenciais vinculada ao endpoint.
OpenShell é o runtime seguro e privado para agentes de IA autônomos. Ele fornece ambientes de execução em sandbox que protegem seus dados, credenciais e infraestrutura — governados por políticas YAML declarativas que impedem acesso não autorizado a arquivos, exfiltração de dados e atividade de rede não controlada.
O OpenShell foi construído com foco em agentes. Ele inclui habilidades públicas de agente para usar e operar o OpenShell, além de fluxos de trabalho separados cientes do repositório para contribuidores e mantenedores.
Binário (recomendado):```bash curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
O instalador instala a versão estável mais recente por padrão. Para instalar uma versão específica, defina `OPENSHELL_VERSION`. Uma [versão `dev`](https://github.com/NVIDIA/OpenShell/releases/tag/dev) também está disponível e acompanha o commit mais recente em `main`.
O pacote `openshell` no PyPI fornece apenas o SDK Python. Ele não instala a CLI `openshell`. Adicione o SDK a um projeto Python com [uv](https://docs.astral.sh/uv/):```bash
uv add openshell
Helm chart:
Experimental — o caminho de implantação no Kubernetes está em desenvolvimento ativo. Espere arestas ásperas e mudanças que quebram compatibilidade.
Implante o gateway OpenShell em um cluster Kubernetes a partir do chart OCI publicado no GHCR:```bash helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart
Consulte [`deploy/helm/openshell/README.md`](https://github.com/nvidia/openshell/blob/main/deploy/helm/openshell/README.md) para versões disponíveis, convenções de tags de desenvolvimento e configuração.
Para implantar o OpenShell no OpenShift, consulte [`deploy/helm/openshell/README.md#install-on-openshift`](https://github.com/nvidia/openshell/blob/main/deploy/helm/openshell/README.md#install-on-openshift).
### Criar um sandbox```bash
openshell sandbox create -- claude # or opencode, codex, copilot
O contêiner sandbox inclui as seguintes ferramentas por padrão:
Para mais detalhes, consulte https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base.
Todo sandbox começa com acesso de saída mínimo. Você abre acesso adicional com uma política YAML curta que o proxy aplica no nível de método e caminho HTTP, sem reiniciar nada.```bash
openshell sandbox create
sandbox$ curl -sS https://api.github.com/zen curl: (56) Received HTTP code 403 from proxy after CONNECT
sandbox$ exit openshell policy set demo --policy examples/sandbox-policy-quickstart/policy.yaml --wait
openshell sandbox connect demo sandbox$ curl -sS https://api.github.com/zen Anything added dilutes everything else.
sandbox$ curl -sS -X POST https://api.github.com/repos/octocat/hello-world/issues -d '{"title":"oops"}' {"error":"policy_denied","detail":"POST /repos/octocat/hello-world/issues not permitted by policy"}
Veja o [passo a passo completo](https://github.com/nvidia/openshell/blob/main/examples/sandbox-policy-quickstart) ou execute a demonstração automatizada:```bash
bash examples/sandbox-policy-quickstart/demo.sh
O OpenShell isola cada sandbox em seu próprio contêiner com roteamento de saída aplicado por políticas. Um gateway leve coordena o ciclo de vida do sandbox, e cada conexão de saída é interceptada pelo motor de políticas, que faz uma de três coisas:
| Componente |
|---|
O OpenShell executa um plano de controle de gateway que gerencia o ciclo de vida do sandbox por meio de um driver de computação configurado. As plataformas de computação suportadas incluem Docker, Podman, MicroVM e Kubernetes.
O OpenShell aplica defesa em profundidade em quatro domínios de política:
As políticas são arquivos YAML declarativos. Seções estáticas (sistema de arquivos, processo) são bloqueadas na criação; políticas de rede e anexos de provedores podem ser atualizados em um sandbox em execução.
Agentes precisam de credenciais — chaves de API, tokens, contas de serviço. O OpenShell gerencia isso como provedores: pacotes de credenciais nomeados que são injetados nos sandboxes na criação. A CLI descobre automaticamente credenciais para agentes reconhecidos (Claude, Codex, OpenCode, Copilot) a partir do seu ambiente de shell, ou você pode criar provedores explicitamente com openshell provider create. As credenciais nunca vazam para o sistema de arquivos do sandbox; elas são injetadas como variáveis de ambiente em tempo de execução.
O acesso à inferência usa o mesmo fluxo de trabalho de provedores. Anexe um provedor com capacidade de inferência a um sandbox, chame o endpoint nativo do provedor e selecione o modelo no cliente. Os perfis de provedor contribuem com a política de endpoint e vinculam os placeholders de credenciais ao destino autorizado.
Experimental — O passthrough de GPU funciona em hosts suportados, mas está em desenvolvimento ativo. Espere arestas e mudanças disruptivas.
O OpenShell pode passar GPUs do host para os sandboxes para inferência local, ajuste fino ou qualquer carga de trabalho com GPU. Adicione --gpu ao criar um sandbox:```bash
openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude
Sandboxes de GPU com suporte a Docker selecionam automaticamente o CDI quando disponível e, caso contrário, recorrem ao caminho de solicitação de GPU NVIDIA do Docker (`--gpus all`).
**Requisitos:** Os drivers NVIDIA e o [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) devem estar instalados no host. A própria imagem do sandbox deve incluir os drivers e bibliotecas de GPU apropriados para sua carga de trabalho — a imagem `base` padrão não inclui. Consulte o [exemplo BYOC](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) para criar uma imagem de sandbox personalizada com suporte a GPU.
## Agentes Suportados
| Agente | Fonte | Notas |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Funciona imediatamente. O provedor usa `ANTHROPIC_API_KEY`. |
| [OpenCode](https://opencode.ai/) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Funciona imediatamente. O provedor usa `OPENAI_API_KEY` ou `OPENROUTER_API_KEY`. |
| [Codex](https://developers.openai.com/codex) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Funciona imediatamente. O provedor usa `OPENAI_API_KEY`. |
| [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Funciona imediatamente. O provedor usa `GITHUB_TOKEN` ou `COPILOT_GITHUB_TOKEN`. |
| [OpenClaw](https://openclaw.ai/) | [NemoClaw](https://github.com/NVIDIA/NemoClaw) | Execute o OpenClaw com mais segurança dentro do NVIDIA OpenShell com o blueprint NemoClaw. |
| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | [NemoClaw](https://github.com/NVIDIA/NemoClaw) | Execute o Hermes Agent com mais segurança dentro do NVIDIA OpenShell com o blueprint NemoClaw. |
| [Ollama](https://ollama.com/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | Inicie com `openshell sandbox create --from ollama`. |
| [Pi](https://pi.dev/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | Inicie com `openshell sandbox create --from pi`. |
## Comandos Principais
| Comando | Descrição |
| ---------------------------------------------------------- | ----------------------------------------------- |
| `openshell sandbox create -- <agent>` | Cria um sandbox e inicia um agente. |
| `openshell sandbox connect [name]` | Conecta via SSH a um sandbox em execução. |
| `openshell sandbox list` | Lista todos os sandboxes. |
| `openshell provider create --type [type] --from-existing` | Cria um provedor de credenciais a partir de variáveis de ambiente. |
| `openshell sandbox provider attach <sandbox> <provider>` | Anexa um provedor a um sandbox em execução. |
| `openshell policy set <name> --policy file.yaml` | Aplica ou atualiza uma política em um sandbox em execução. |
| `openshell policy get <name>` | Mostra a política ativa. |
| `openshell logs [name] --tail` | Transmite os logs do sandbox. |
| `openshell term` | Inicia a interface de terminal em tempo real para depuração. |
Consulte a [documentação completa](https://docs.nvidia.com/openshell/latest) para guias de comandos, tutoriais e material de referência.
## Interface de Terminal
O OpenShell inclui um painel de terminal em tempo real para monitorar gateways, sandboxes e provedores — inspirado no [k9s](https://k9scli.io/).```bash
openshell term
A TUI oferece uma visão ao vivo e controlada por teclado do seu gateway e sandboxes. Navegue com Tab para alternar entre painéis, j/k para percorrer listas, Enter para selecionar e : para o modo de comando. A integridade do gateway e o status das sandboxes são atualizados automaticamente a cada dois segundos.
Use --from para criar sandboxes a partir do catálogo OpenShell Community ou de uma imagem de contêiner:```bash
openshell sandbox create --from gemini # community catalog
docker build -t my-sandbox:latest ./my-sandbox-dir # Docker gateway
openshell sandbox create --from my-sandbox:latest # Docker built image
podman build -t localhost/my-sandbox:latest ./my-sandbox-dir # Podman gateway
openshell sandbox create --from localhost/my-sandbox:latest # Podman built image
openshell sandbox create --from registry.io/img:v1 # container image
Compile com o mecanismo de contêiner usado pelo seu gateway local. Para um gateway
remoto, envie a imagem para um registro do qual o gateway possa fazer pull.
Consulte o catálogo [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) e o [exemplo BYOC](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) para obter detalhes.
## Use o OpenShell com o Seu Agente
O OpenShell fornece quatro skills portáteis para usuários e operadores: fluxos de trabalho de CLI (`openshell-cli`), solução de problemas do gateway (`debug-openshell-cluster`), solução de problemas de inferência (`debug-inference`) e geração de políticas (`generate-sandbox-policy`). Instale-os com o Agent Skills CLI:```bash
npx skills add NVIDIA/OpenShell
Essas habilidades públicas e instaláveis residem em skills/ e usam a ajuda da CLI instalada e a documentação publicada como suas fontes de verdade. Elas não exigem um checkout do código-fonte do OpenShell.
O OpenShell é desenvolvido usando os mesmos fluxos de trabalho orientados por agentes que ele possibilita. As habilidades de contribuidores e mantenedores residem separadamente em .agents/skills/; elas automatizam o trabalho no repositório do OpenShell e não são incluídas quando os usuários instalam as habilidades públicas:
create-spike; um humano o aceita com state:accepted ou posicionamento no roadmap, ou o recusa. O trabalho aceito pode permanecer sob responsabilidade humana ou entrar no fluxo de trabalho opcional e controlado por humanos de planejamento e implementação agent:*.triage-issue. Os agentes estabelecem a validade técnica e o impacto; os humanos decidem se o projeto deve agir e onde o trabalho se posiciona no roadmap.review-security-issue produz uma avaliação de severidade e um plano de remediação. fix-security-issue o implementa.sync-agent-infra, update-docs-from-commits e outros fluxos de trabalho internos mantêm o código, a documentação e a infraestrutura de agentes consistentes.A implementação por agentes é dirigida por humanos: um usuário pode solicitar uma fase diretamente, ou os mantenedores podem usar o fluxo de trabalho opcional agent:* para enfileirar e aprovar o planejamento e a implementação. Consulte AGENTS.md para a documentação completa da cadeia de fluxos de trabalho.
npx skills add NVIDIA/OpenShellrfcO OpenShell é construído com agentes em primeiro lugar. As issues devem incluir uma história de usuário, declaração do problema, impacto e critérios de aceitação. O impacto deve explicar as consequências do comportamento atual e por que as soluções alternativas existentes são insuficientes. Solicitações de recursos também exigem um design proposto em nível de fluxo de trabalho e alternativas; relatórios de bugs adicionam etapas de reprodução, detalhes do ambiente e logs relevantes. Uma vez que o trabalho é autorizado através do fluxo de trabalho do projeto ou de uma solicitação direta, os contribuidores devem usar as habilidades em .agents/skills/ para investigar o código e o comportamento atuais, implementar a mudança e verificá-la. Se uma issue contiver diagnósticos anteriores, verifique-os em vez de confiar neles. Consulte CONTRIBUTING.md para a tabela completa de habilidades de agentes, o fluxo de trabalho de contribuição e a configuração de desenvolvimento.
O OpenShell coleta telemetria anônima para ajudar a melhorar o projeto para desenvolvedores. Esses dados não são usados para rastrear o comportamento individual do usuário. Eles nos ajudam a entender o uso agregado dos fluxos de trabalho de sandbox, provedor e políticas, para que possamos priorizar melhorias de produto e compartilhar tendências de uso com a comunidade.
Desative a telemetria em tempo de execução definindo OPENSHELL_TELEMETRY_ENABLED=false na implantação do gateway. Para instalações via Helm, defina server.telemetryEnabled=false. O OpenShell propaga essa configuração de implantação para os ambientes do supervisor do sandbox, de modo que a coleta de telemetria do lado do sandbox também seja desativada.
Você também pode compilar a telemetria completamente fora. O suporte à telemetria é um recurso Cargo telemetry ativado por padrão, e cada crate que o carrega também define um alias defaults-without-telemetry cobrindo todos os outros recursos padrão. Compile artefatos sem telemetria com --no-default-features --features defaults-without-telemetry:```shell
cargo build --release -p openshell-gateway --no-default-features --features defaults-without-telemetry
cargo build --release -p openshell-sandbox --no-default-features --features defaults-without-telemetry
cargo build --release -p openshell-driver-vm --no-default-features --features defaults-without-telemetry
Os binários resultantes não contêm nenhum endpoint de telemetria, nenhum cliente HTTP de telemetria e nenhum código de emissão. Com a telemetria compilada fora, o gateway não emite nada e reporta a telemetria como desativada às sandboxes que lança. O Cargo não tem forma de subtrair uma única feature padrão, pelo que `defaults-without-telemetry` tem de ser emparelhado com `--no-default-features`; passá-lo isoladamente deixa os padrões em vigor e falha a compilação em vez de produzir um binário que ainda emite.
O gateway também expõe features Cargo separadas para os seus drivers de computação incorporados: `compute-driver-kubernetes`, `compute-driver-docker`, `compute-driver-podman`, `compute-driver-vm` e `compute-driver-mxc`. Desative o conjunto de features padrão e, em seguida, ative apenas os drivers e o modo de telemetria exigidos pelo binário de destino. Por exemplo:```shell
# Docker only, with telemetry support.
cargo build --release -p openshell-gateway --no-default-features --features telemetry,compute-driver-docker
# Docker and VM only, with telemetry compiled out.
cargo build --release -p openshell-gateway --no-default-features --features compute-driver-docker,compute-driver-vm
# Windows MXC only, with telemetry support and bundled Z3.
cargo build --release -p openshell-gateway --no-default-features --features telemetry,compute-driver-mxc,bundled-z3
Builds regulares mantêm seu conjunto de drivers de plataforma através do recurso de compatibilidade padrão in-tree-compute-drivers. No Windows, compute-driver-mxc seleciona o MXC; os outros quatro recursos instalam stubs de drivers não suportados. Em outras plataformas, o MXC é excluído.
Os eventos de telemetria são limitados a categorias operacionais anônimas e contagens, como resultados do ciclo de vida do sandbox, buckets de perfil de provedor, contagens de decisões de política e categorias agregadas de negação de atividade de rede. A telemetria do OpenShell não coleta nomes ou IDs de sandbox, nomes de host, caminhos de arquivo, caminhos de binários, prompts, credenciais, nomes de provedores, nomes de modelos ou conteúdo do usuário.
A desativação se aplica apenas à telemetria emitida pelo OpenShell. Serviços de terceiros, provedores de modelos, endpoints de inferência, agentes ou ferramentas que você configura e usa com o OpenShell podem ter seus próprios termos e práticas de privacidade.
Publicamos tendências agregadas de uso a partir desta telemetria a cada duas semanas. Consulte os relatórios de telemetria da comunidade para o resumo mais recente.
Este software recupera, acessa ou interage automaticamente com materiais externos. Esses materiais recuperados não são distribuídos com este software e são regidos exclusivamente por termos, condições e licenças separados. Você é o único responsável por encontrar, revisar e cumprir todos os termos, condições e licenças aplicáveis, e por verificar a segurança, integridade e adequação de quaisquer materiais recuperados para o seu caso de uso específico. Este software é fornecido "COMO ESTÁ", sem garantia de qualquer tipo. O autor não faz nenhuma representação ou garantia em relação a quaisquer materiais recuperados, e não assume nenhuma responsabilidade por quaisquer perdas, danos, responsabilidades ou consequências legais decorrentes do seu uso ou incapacidade de usar este software ou quaisquer materiais recuperados. Use este software e os materiais recuperados por sua conta e risco.
Este projeto está licenciado sob a Apache License 2.0.
| Categoria | Ferramentas |
|---|
| Agente | claude, opencode, codex, copilot |
| Linguagem | python (3.14), node (22) |
| Desenvolvedor | gh, git, vim, nano |
| Rede | ping, dig, nslookup, nc, traceroute, netstat |
| Função |
|---|
| Gateway | API de plano de controle que coordena o ciclo de vida do sandbox e atua como limite de autenticação. |
| Sandbox | Runtime isolado com supervisão de contêiner e roteamento de saída aplicado por políticas. |
| Motor de Políticas | Aplica restrições de sistema de arquivos, rede e processos da camada de aplicação até o kernel. |
| Acesso a Provedores | Endpoints definidos por perfil, política de binários e injeção de credenciais vinculadas a endpoints para APIs de modelos e outros serviços. |
| Camada | O que protege | Quando se aplica |
|---|
| Sistema de Arquivos | Impede leituras/escritas fora dos caminhos permitidos. | Bloqueado na criação do sandbox. |
| Rede | Bloqueia conexões de saída não autorizadas. | Recarregável a quente em tempo de execução. |
| Processo | Bloqueia escalonamento de privilégios e syscalls perigosas. | Bloqueado na criação do sandbox. |
| Provedores | Concede credenciais vinculadas a endpoints e acesso à rede. | Recarregável a quente em tempo de execução. |