Runtime sandboxed per agenti AI autonomi con policy YAML dichiarative che applicano vincoli su filesystem, rete e processi, oltre all'iniezione di credenziali vincolate all'endpoint.
OpenShell è il runtime sicuro e privato per agenti AI autonomi. Fornisce ambienti di esecuzione sandboxed che proteggono i tuoi dati, le credenziali e l'infrastruttura — governati da policy YAML dichiarative che impediscono accessi non autorizzati ai file, esfiltrazione di dati e attività di rete non controllata.
OpenShell è progettato agent-first. Include competenze pubbliche per agenti per l'utilizzo e la gestione di OpenShell, oltre a flussi di lavoro separati consapevoli del repository per contributori e maintainer.
Binario (consigliato):```bash curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
L'installer installa per impostazione predefinita l'ultima release stabile. Per installare una versione specifica, impostare `OPENSHELL_VERSION`. È inoltre disponibile una [release `dev`](https://github.com/NVIDIA/OpenShell/releases/tag/dev) che segue l'ultimo commit su `main`.
Il pacchetto `openshell` su PyPI fornisce solo l'SDK Python. Non installa la CLI `openshell`. Aggiungere l'SDK a un progetto Python con [uv](https://docs.astral.sh/uv/):```bash
uv add openshell
Helm chart:
Sperimentale — il percorso di deployment Kubernetes è in fase di sviluppo attivo. Aspettatevi imperfezioni e modifiche che potrebbero rompere la compatibilità.
Distribuisci il gateway OpenShell in un cluster Kubernetes dal chart OCI pubblicato su GHCR:```bash helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart
Vedi [`deploy/helm/openshell/README.md`](https://github.com/nvidia/openshell/blob/main/deploy/helm/openshell/README.md) per le versioni disponibili, le convenzioni dei tag di sviluppo e la configurazione.
Per distribuire OpenShell su OpenShift, vedi [`deploy/helm/openshell/README.md#install-on-openshift`](https://github.com/nvidia/openshell/blob/main/deploy/helm/openshell/README.md#install-on-openshift).
### Creare una sandbox```bash
openshell sandbox create -- claude # or opencode, codex, copilot
Il container sandbox include i seguenti strumenti per impostazione predefinita:
Per maggiori dettagli consultare https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base.
Ogni sandbox parte con accesso in uscita minimale. È possibile aprire accessi aggiuntivi con una breve policy YAML che il proxy applica a livello di metodo e percorso HTTP, senza riavviare nulla.```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"}
Consulta il [walkthrough completo](https://github.com/nvidia/openshell/blob/main/examples/sandbox-policy-quickstart) oppure esegui la demo automatizzata:```bash
bash examples/sandbox-policy-quickstart/demo.sh
OpenShell isola ogni sandbox nel proprio container con routing in uscita applicato tramite policy. Un gateway leggero coordina il ciclo di vita delle sandbox, e ogni connessione in uscita viene intercettata dal motore di policy, che esegue una delle tre azioni seguenti:
| Componente |
|---|
OpenShell esegue un piano di controllo gateway che gestisce il ciclo di vita delle sandbox tramite un driver di calcolo configurato. Le piattaforme di calcolo supportate includono Docker, Podman, MicroVM e Kubernetes.
OpenShell applica una difesa in profondità su quattro domini di policy:
Le policy sono file YAML dichiarativi. Le sezioni statiche (filesystem, process) vengono bloccate alla creazione; la policy di rete e gli allegati dei provider possono essere aggiornati su una sandbox in esecuzione.
Gli agenti necessitano di credenziali — chiavi API, token, service account. OpenShell le gestisce come provider: bundle di credenziali denominati che vengono iniettati nelle sandbox alla creazione. La CLI rileva automaticamente le credenziali per gli agenti riconosciuti (Claude, Codex, OpenCode, Copilot) dal tuo ambiente shell, oppure puoi creare provider esplicitamente con openshell provider create. Le credenziali non trapelano mai nel filesystem della sandbox; vengono iniettate come variabili d'ambiente a runtime.
L'accesso all'inferenza utilizza lo stesso flusso di lavoro dei provider. Allega un provider abilitato all'inferenza a una sandbox, chiama l'endpoint nativo del provider e seleziona il modello nel client. I profili dei provider forniscono la policy degli endpoint e associano i segnaposto delle credenziali alla destinazione autorizzata.
Sperimentale — il passthrough della GPU funziona su host supportati ma è in fase di sviluppo attivo. Aspettati imperfezioni e modifiche incompatibili.
OpenShell può passare le GPU dell'host nelle sandbox per inferenza locale, fine-tuning o qualsiasi carico di lavoro GPU. Aggiungi --gpu durante la creazione di una sandbox:```bash
openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude
Le sandbox GPU basate su Docker selezionano automaticamente CDI quando disponibile e, in caso contrario, ricorrono al percorso di richiesta GPU NVIDIA di Docker (`--gpus all`).
**Requisiti:** i driver NVIDIA e il [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) devono essere installati sull'host. L'immagine del sandbox stessa deve includere i driver e le librerie GPU appropriati per il tuo workload — l'immagine predefinita `base` non li include. Consulta l'[esempio BYOC](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) per creare un'immagine sandbox personalizzata con supporto GPU.
## Agenti supportati
| Agente | Sorgente | Note |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Funziona subito. Il provider utilizza `ANTHROPIC_API_KEY`. |
| [OpenCode](https://opencode.ai/) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Funziona subito. Il provider utilizza `OPENAI_API_KEY` o `OPENROUTER_API_KEY`. |
| [Codex](https://developers.openai.com/codex) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Funziona subito. Il provider utilizza `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) | Funziona subito. Il provider utilizza `GITHUB_TOKEN` o `COPILOT_GITHUB_TOKEN`. |
| [OpenClaw](https://openclaw.ai/) | [NemoClaw](https://github.com/NVIDIA/NemoClaw) | Esegui OpenClaw in modo più sicuro all'interno di NVIDIA OpenShell con il blueprint NemoClaw. |
| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | [NemoClaw](https://github.com/NVIDIA/NemoClaw) | Esegui Hermes Agent in modo più sicuro all'interno di NVIDIA OpenShell con il blueprint NemoClaw. |
| [Ollama](https://ollama.com/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | Avvia con `openshell sandbox create --from ollama`. |
| [Pi](https://pi.dev/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | Avvia con `openshell sandbox create --from pi`. |
## Comandi principali
| Comando | Descrizione |
| ---------------------------------------------------------- | ----------------------------------------------- |
| `openshell sandbox create -- <agent>` | Crea un sandbox e avvia un agente. |
| `openshell sandbox connect [name]` | Accedi via SSH a un sandbox in esecuzione. |
| `openshell sandbox list` | Elenca tutti i sandbox. |
| `openshell provider create --type [type] --from-existing` | Crea un provider di credenziali dalle variabili d'ambiente. |
| `openshell sandbox provider attach <sandbox> <provider>` | Collega un provider a un sandbox in esecuzione. |
| `openshell policy set <name> --policy file.yaml` | Applica o aggiorna una policy su un sandbox in esecuzione. |
| `openshell policy get <name>` | Mostra la policy attiva. |
| `openshell logs [name] --tail` | Trasmetti in streaming i log del sandbox. |
| `openshell term` | Avvia l'interfaccia terminale in tempo reale per il debug. |
Consulta la [documentazione completa](https://docs.nvidia.com/openshell/latest) per guide ai comandi, tutorial e materiale di riferimento.
## Interfaccia terminale
OpenShell include una dashboard terminale in tempo reale per il monitoraggio di gateway, sandbox e provider — ispirata a [k9s](https://k9scli.io/).```bash
openshell term
La TUI offre una vista live e controllata da tastiera del tuo gateway e dei tuoi sandbox. Naviga con Tab per cambiare pannello, j/k per muoverti tra le liste, Enter per selezionare e : per la modalità comando. Lo stato di salute del gateway e lo stato dei sandbox si aggiornano automaticamente ogni due secondi.
Usa --from per creare sandbox dal catalogo OpenShell Community o da un'immagine container:```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
Crea l'immagine con il container engine utilizzato dal tuo gateway locale. Per un
gateway remoto, esegui il push dell'immagine su un registry da cui il gateway possa fare pull.
Consulta il catalogo [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) e l'[esempio BYOC](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) per i dettagli.
## Usare OpenShell con il tuo Agent
OpenShell fornisce quattro skill portabili per utenti e operatori: flussi di lavoro CLI (`openshell-cli`), risoluzione dei problemi del gateway (`debug-openshell-cluster`), risoluzione dei problemi di inferenza (`debug-inference`) e generazione di policy (`generate-sandbox-policy`). Installale con la CLI Agent Skills:```bash
npx skills add NVIDIA/OpenShell
Queste competenze pubbliche e installabili risiedono in skills/ e utilizzano l'help della CLI installata e la documentazione pubblicata come fonti di verità. Non richiedono un checkout del codice sorgente di OpenShell.
OpenShell è sviluppato utilizzando gli stessi flussi di lavoro guidati dagli agenti che abilita. Le competenze per contributori e maintainer risiedono separatamente in .agents/skills/; automatizzano il lavoro sul repository OpenShell e non sono incluse quando gli utenti installano le competenze pubbliche:
create-spike; un umano lo accetta con state:accepted o con l'inserimento nella roadmap, oppure lo rifiuta. Il lavoro accettato può rimanere di proprietà umana o entrare nel flusso di lavoro opzionale, controllato da umani, di pianificazione e implementazione agent:*.triage-issue. Gli agenti stabiliscono la validità tecnica e l'impatto; gli umani decidono se il progetto debba agire e dove si colloca il lavoro nella roadmap.review-security-issue produce una valutazione di gravità e un piano di remediation. fix-security-issue lo implementa.sync-agent-infra, update-docs-from-commits e altri flussi di lavoro interni mantengono coerenti codice, documentazione e infrastruttura degli agenti.L'implementazione da parte degli agenti è guidata dagli umani: un utente può richiedere direttamente una fase, oppure i maintainer possono utilizzare il flusso di lavoro opzionale agent:* per accodare e approvare pianificazione e implementazione. Consulta AGENTS.md per la documentazione completa della catena di flussi di lavoro.
npx skills add NVIDIA/OpenShellrfcOpenShell è costruito agent-first. Le issue dovrebbero includere una user story, una dichiarazione del problema, l'impatto e i criteri di accettazione. L'impatto dovrebbe spiegare le conseguenze del comportamento attuale e perché le soluzioni alternative esistenti sono insufficienti. Le richieste di funzionalità richiedono inoltre una progettazione proposta a livello di flusso di lavoro e alternative; le segnalazioni di bug aggiungono passaggi di riproduzione, dettagli sull'ambiente e log rilevanti. Una volta che il lavoro è autorizzato tramite il flusso di lavoro del progetto o una richiesta diretta, i contributori dovrebbero utilizzare le competenze in .agents/skills/ per indagare il codice e il comportamento attuali, implementare la modifica e verificarla. Se una issue contiene diagnostiche precedenti, verificale invece di fidarti di esse. Consulta CONTRIBUTING.md per la tabella completa delle competenze degli agenti, il flusso di lavoro di contribuzione e la configurazione di sviluppo.
OpenShell raccoglie telemetria anonima per contribuire a migliorare il progetto per gli sviluppatori. Questi dati non vengono utilizzati per tracciare il comportamento dei singoli utenti. Ci aiutano a comprendere l'utilizzo aggregato dei flussi di lavoro di sandbox, provider e policy, così possiamo dare priorità ai miglioramenti del prodotto e condividere le tendenze di utilizzo con la community.
Disabilita la telemetria a runtime impostando OPENSHELL_TELEMETRY_ENABLED=false sul deployment del gateway. Per le installazioni Helm, imposta server.telemetryEnabled=false. OpenShell propaga questa impostazione di deployment negli ambienti del supervisore della sandbox, così anche la raccolta di telemetria lato sandbox viene disabilitata.
Puoi anche compilare la telemetria completamente fuori. Il supporto alla telemetria è una feature Cargo telemetry attiva per impostazione predefinita, e ogni crate che la contiene definisce anche un alias defaults-without-telemetry che copre tutte le altre feature predefinite. Compila artefatti senza telemetria con --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
I binari risultanti non contengono alcun endpoint di telemetria, alcun client HTTP di telemetria e alcun codice di emissione. Con la telemetria compilata fuori, il gateway non emette nulla e segnala la telemetria come disabilitata alle sandbox che avvia. Cargo non ha modo di sottrarre una singola feature predefinita, quindi `defaults-without-telemetry` deve essere abbinata a `--no-default-features`; passandola da sola lascia le impostazioni predefinite in vigore e fa fallire la build anziché produrre un binario che emette ancora.
Il gateway espone anche feature Cargo separate per i suoi driver di calcolo integrati: `compute-driver-kubernetes`, `compute-driver-docker`, `compute-driver-podman`, `compute-driver-vm` e `compute-driver-mxc`. Disabilita l'insieme di feature predefinite, quindi abilita solo i driver e la modalità di telemetria richiesti dal binario di destinazione. Ad esempio:```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
Le build regolari mantengono il proprio set di driver di piattaforma tramite la funzionalità di compatibilità predefinita in-tree-compute-drivers. Su Windows, compute-driver-mxc seleziona MXC; le altre quattro funzionalità installano stub di driver non supportati. Sulle altre piattaforme, MXC è escluso.
Gli eventi di telemetria sono limitati a categorie operative anonime e conteggi, come esiti del ciclo di vita della sandbox, bucket dei profili dei provider, conteggi delle decisioni di policy e categorie aggregate di diniego dell'attività di rete. La telemetria di OpenShell non raccoglie nomi o ID delle sandbox, hostname, percorsi di file, percorsi di binari, prompt, credenziali, nomi dei provider, nomi dei modelli o contenuti degli utenti.
La rinuncia si applica solo alla telemetria emessa da OpenShell. Servizi di terze parti, provider di modelli, endpoint di inferenza, agenti o strumenti che configuri e utilizzi con OpenShell possono avere i propri termini e pratiche sulla privacy.
Pubblichiamo tendenze di utilizzo aggregate da questa telemetria ogni due settimane. Consulta i report di telemetria della community per il riepilogo più recente.
Questo software recupera, accede o interagisce automaticamente con materiali esterni. Tali materiali recuperati non sono distribuiti con questo software e sono disciplinati esclusivamente da termini, condizioni e licenze separati. Sei l'unico responsabile di trovare, esaminare e rispettare tutti i termini, le condizioni e le licenze applicabili, e di verificare la sicurezza, l'integrità e l'idoneità di qualsiasi materiale recuperato per il tuo specifico caso d'uso. Questo software è fornito "COSÌ COM'È", senza garanzie di alcun tipo. L'autore non rilascia alcuna dichiarazione o garanzia riguardo a qualsiasi materiale recuperato, e non si assume alcuna responsabilità per eventuali perdite, danni, responsabilità o conseguenze legali derivanti dal tuo utilizzo o dall'impossibilità di utilizzare questo software o qualsiasi materiale recuperato. Utilizza questo software e i materiali recuperati a tuo rischio.
Questo progetto è concesso in licenza sotto la Apache License 2.0.
| Categoria | Strumenti |
|---|
| Agent | claude, opencode, codex, copilot |
| Linguaggio | python (3.14), node (22) |
| Sviluppo | gh, git, vim, nano |
| Rete | ping, dig, nslookup, nc, traceroute, netstat |
| Ruolo |
|---|
| Gateway | API del piano di controllo che coordina il ciclo di vita delle sandbox e funge da confine di autenticazione. |
| Sandbox | Runtime isolato con supervisione dei container e routing in uscita applicato tramite policy. |
| Policy Engine | Applica i vincoli su filesystem, rete e processi dal livello applicativo fino al kernel. |
| Provider Access | Endpoint definiti dal profilo, policy sui binari e iniezione di credenziali associate agli endpoint per le API dei modelli e altri servizi. |
| Livello | Cosa protegge | Quando si applica |
|---|
| Filesystem | Impedisce letture/scritture al di fuori dei percorsi consentiti. | Bloccato alla creazione della sandbox. |
| Network | Blocca le connessioni in uscita non autorizzate. | Ricaricabile a caldo a runtime. |
| Process | Blocca l'escalation di privilegi e le syscall pericolose. | Bloccato alla creazione della sandbox. |
| Providers | Concede credenziali associate agli endpoint e accesso alla rete. | Ricaricabile a caldo a runtime. |