{"id":47573739,"url":"https://github.com/NVIDIA/OpenShell","last_synced_at":"2026-04-01T20:02:00.558Z","repository":{"id":344840720,"uuid":"1166129534","full_name":"NVIDIA/OpenShell","owner":"NVIDIA","description":"OpenShell is the safe, private runtime for autonomous AI agents.","archived":false,"fork":false,"pushed_at":"2026-03-25T21:40:29.000Z","size":28213,"stargazers_count":3768,"open_issues_count":53,"forks_count":371,"subscribers_count":12,"default_branch":"main","last_synced_at":"2026-03-25T22:54:35.985Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.nvidia.com/openshell/latest/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NVIDIA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":"DCO","cla":null}},"created_at":"2026-02-24T22:52:22.000Z","updated_at":"2026-03-25T22:46:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/NVIDIA/OpenShell","commit_stats":null,"previous_names":["nvidia/openshell"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/NVIDIA/OpenShell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2FOpenShell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2FOpenShell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2FOpenShell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2FOpenShell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NVIDIA","download_url":"https://codeload.github.com/NVIDIA/OpenShell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2FOpenShell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291337,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-30T23:00:26.306Z","updated_at":"2026-04-01T20:02:00.550Z","avatar_url":"https://github.com/NVIDIA.png","language":"Rust","readme":"# OpenShell\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://github.com/NVIDIA/OpenShell/blob/main/LICENSE)\n[![PyPI](https://img.shields.io/badge/PyPI-openshell-orange?logo=pypi)](https://pypi.org/project/openshell/)\n[![Security Policy](https://img.shields.io/badge/Security-Report%20a%20Vulnerability-red)](SECURITY.md)\n[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen)](https://docs.nvidia.com/openshell/latest/index.html)\n[![Project Status](https://img.shields.io/badge/status-alpha-orange)](https://docs.nvidia.com/openshell/latest/about/release-notes.html)\n\nOpenShell is the safe, private runtime for autonomous AI agents. It provides sandboxed execution environments that protect your data, credentials, and infrastructure — governed by declarative YAML policies that prevent unauthorized file access, data exfiltration, and uncontrolled network activity.\n\nOpenShell is built agent-first. The project ships with agent skills for everything from cluster debugging to policy generation, and we expect contributors to use them.\n\n\u003e **Alpha software — single-player mode.** OpenShell is proof-of-life: one developer, one environment, one gateway. We are building toward multi-tenant enterprise deployments, but the starting point is getting your own environment up and running. Expect rough edges. Bring your agent.\n\n## Quickstart\n\n### Prerequisites\n\n- **Docker** — Docker Desktop (or a Docker daemon) must be running.\n\n### Install\n\n**Binary (recommended):**\n\n```bash\ncurl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh\n```\n\n**From PyPI (requires [uv](https://docs.astral.sh/uv/)):**\n\n```bash\nuv tool install -U openshell\n```\n\nBoth methods install the latest stable release by default. To install a specific version, set `OPENSHELL_VERSION` (binary) or pin the version with `uv tool install openshell==\u003cversion\u003e`. A [`dev` release](https://github.com/NVIDIA/OpenShell/releases/tag/dev) is also available that tracks the latest commit on `main`.\n\n### Create a sandbox\n\n```bash\nopenshell sandbox create -- claude  # or opencode, codex, copilot\n```\n\nA gateway is created automatically on first use. To deploy on a remote host instead, pass `--remote user@host` to the create command.\n\nThe sandbox container includes the following tools by default:\n\n| Category   | Tools                                                    |\n| ---------- | -------------------------------------------------------- |\n| Agent      | `claude`, `opencode`, `codex`, `copilot`                 |\n| Language   | `python` (3.13), `node` (22)                             |\n| Developer  | `gh`, `git`, `vim`, `nano`                               |\n| Networking | `ping`, `dig`, `nslookup`, `nc`, `traceroute`, `netstat` |\n\nFor more details see https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base.\n\n### See network policy in action\n\nEvery sandbox starts with **minimal outbound access**. You open additional access with a short YAML policy that the proxy enforces at the HTTP method and path level, without restarting anything.\n\n```bash\n# 1. Create a sandbox (starts with minimal outbound access)\nopenshell sandbox create\n\n# 2. Inside the sandbox — blocked\nsandbox$ curl -sS https://api.github.com/zen\ncurl: (56) Received HTTP code 403 from proxy after CONNECT\n\n# 3. Back on the host — apply a read-only GitHub API policy\nsandbox$ exit\nopenshell policy set demo --policy examples/sandbox-policy-quickstart/policy.yaml --wait\n\n# 4. Reconnect — GET allowed, POST blocked by L7\nopenshell sandbox connect demo\nsandbox$ curl -sS https://api.github.com/zen\nAnything added dilutes everything else.\n\nsandbox$ curl -sS -X POST https://api.github.com/repos/octocat/hello-world/issues -d '{\"title\":\"oops\"}'\n{\"error\":\"policy_denied\",\"detail\":\"POST /repos/octocat/hello-world/issues not permitted by policy\"}\n```\n\nSee the [full walkthrough](examples/sandbox-policy-quickstart/) or run the automated demo:\n\n```bash\nbash examples/sandbox-policy-quickstart/demo.sh\n```\n\n## How It Works\n\nOpenShell isolates each sandbox in its own container with policy-enforced egress routing. A lightweight gateway coordinates sandbox lifecycle, and every outbound connection is intercepted by the policy engine, which does one of three things:\n\n- **Allows** — the destination and binary match a policy block.\n- **Routes for inference** — strips caller credentials, injects backend credentials, and forwards to the managed model.\n- **Denies** — blocks the request and logs it.\n\n| Component          | Role                                                                                         |\n| ------------------ | -------------------------------------------------------------------------------------------- |\n| **Gateway**        | Control-plane API that coordinates sandbox lifecycle and acts as the auth boundary.          |\n| **Sandbox**        | Isolated runtime with container supervision and policy-enforced egress routing.              |\n| **Policy Engine**  | Enforces filesystem, network, and process constraints from application layer down to kernel. |\n| **Privacy Router** | Privacy-aware LLM routing that keeps sensitive context on sandbox compute.                   |\n\nUnder the hood, all these components run as a [K3s](https://k3s.io/) Kubernetes cluster inside a single Docker container — no separate K8s install required. The `openshell gateway` commands take care of provisioning the container and cluster.\n\n## Protection Layers\n\nOpenShell applies defense in depth across four policy domains:\n\n| Layer      | What it protects                                    | When it applies             |\n| ---------- | --------------------------------------------------- | --------------------------- |\n| Filesystem | Prevents reads/writes outside allowed paths.        | Locked at sandbox creation. |\n| Network    | Blocks unauthorized outbound connections.           | Hot-reloadable at runtime.  |\n| Process    | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. |\n| Inference  | Reroutes model API calls to controlled backends.    | Hot-reloadable at runtime.  |\n\nPolicies are declarative YAML files. Static sections (filesystem, process) are locked at creation; dynamic sections (network, inference) can be hot-reloaded on a running sandbox with `openshell policy set`.\n\n## Providers\n\nAgents need credentials — API keys, tokens, service accounts. OpenShell manages these as **providers**: named credential bundles that are injected into sandboxes at creation. The CLI auto-discovers credentials for recognized agents (Claude, Codex, OpenCode, Copilot) from your shell environment, or you can create providers explicitly with `openshell provider create`. Credentials never leak into the sandbox filesystem; they are injected as environment variables at runtime.\n\n## GPU Support (Experimental)\n\n\u003e **Experimental** — GPU passthrough works on supported hosts but is under active development. Expect rough edges and breaking changes.\n\nOpenShell can pass host GPUs into sandboxes for local inference, fine-tuning, or any GPU workload. Add `--gpu` when creating a sandbox:\n\n```bash\nopenshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude\n```\n\nThe CLI auto-bootstraps a GPU-enabled gateway on first use. GPU intent is also inferred automatically for community images with `gpu` in the name.\n\n**Requirements:** NVIDIA drivers and the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) must be installed on the host. The sandbox image itself must include the appropriate GPU drivers and libraries for your workload — the default `base` image does not. See the [BYOC example](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) for building a custom sandbox image with GPU support.\n\n## Supported Agents\n\n| Agent                                                         | Source                                                                           | Notes                                                                         |\n| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Works out of the box. Provider uses `ANTHROPIC_API_KEY`.                      |\n| [OpenCode](https://opencode.ai/)                              | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Works out of the box. Provider uses `OPENAI_API_KEY` or `OPENROUTER_API_KEY`. |\n| [Codex](https://developers.openai.com/codex)                  | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Works out of the box. Provider uses `OPENAI_API_KEY`.                         |\n| [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) | Works out of the box. Provider uses `GITHUB_TOKEN` or `COPILOT_GITHUB_TOKEN`. |\n| [OpenClaw](https://openclaw.ai/)                              | [Community](https://github.com/NVIDIA/OpenShell-Community)                       | Launch with `openshell sandbox create --from openclaw`.                       |\n| [Ollama](https://ollama.com/)                                 | [Community](https://github.com/NVIDIA/OpenShell-Community)                       | Launch with `openshell sandbox create --from ollama`.                         |\n\n## Key Commands\n\n| Command                                                    | Description                                     |\n| ---------------------------------------------------------- | ----------------------------------------------- |\n| `openshell sandbox create -- \u003cagent\u003e`                      | Create a sandbox and launch an agent.           |\n| `openshell sandbox connect [name]`                         | SSH into a running sandbox.                     |\n| `openshell sandbox list`                                   | List all sandboxes.                             |\n| `openshell provider create --type [type]] --from-existing` | Create a credential provider from env vars.     |\n| `openshell policy set \u003cname\u003e --policy file.yaml`           | Apply or update a policy on a running sandbox.  |\n| `openshell policy get \u003cname\u003e`                              | Show the active policy.                         |\n| `openshell inference set --provider \u003cp\u003e --model \u003cm\u003e`       | Configure the `inference.local` endpoint.       |\n| `openshell logs [name] --tail`                             | Stream sandbox logs.                            |\n| `openshell term`                                           | Launch the real-time terminal UI for debugging. |\n\nSee the full [CLI reference](https://github.com/NVIDIA/OpenShell/blob/main/docs/reference/cli.md) for all commands, flags, and environment variables.\n\n## Terminal UI\n\nOpenShell includes a real-time terminal dashboard for monitoring gateways, sandboxes, and providers — inspired by [k9s](https://k9scli.io/).\n\n```bash\nopenshell term\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/openshell-terminal.png\" alt=\"OpenShell Terminal UI\"\u003e\n\u003c/p\u003e\n\nThe TUI gives you a live, keyboard-driven view of your cluster. Navigate with `Tab` to switch panels, `j`/`k` to move through lists, `Enter` to select, and `:` for command mode. Cluster health and sandbox status auto-refresh every two seconds.\n\n## Community Sandboxes and BYOC\n\nUse `--from` to create sandboxes from the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) catalog, a local directory, or a container image:\n\n```bash\nopenshell sandbox create --from openclaw           # community catalog\nopenshell sandbox create --from ./my-sandbox-dir   # local Dockerfile\nopenshell sandbox create --from registry.io/img:v1 # container image\n```\n\nSee the [community sandboxes](https://github.com/NVIDIA/OpenShell/blob/main/docs/sandboxes/community-sandboxes.md) catalog and the [BYOC example](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) for details.\n\n## Explore with Your Agent\n\nClone the repo and point your coding agent at it. The project includes agent skills that can answer questions, walk you through workflows, and diagnose problems — no issue filing required.\n\n```bash\ngit clone https://github.com/NVIDIA/OpenShell.git   # or git@github.com:NVIDIA/OpenShell.git\ncd OpenShell\n# Point your agent here — it will discover the skills in .agents/skills/ automatically\n```\n\nYour agent can load skills for CLI usage (`openshell-cli`), cluster troubleshooting (`debug-openshell-cluster`), inference troubleshooting (`debug-inference`), policy generation (`generate-sandbox-policy`), and more. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full skills table.\n\n## Built With Agents\n\nOpenShell is developed using the same agent-driven workflows it enables. The `.agents/skills/` directory contains workflow automation that powers the project's development cycle:\n\n- **Spike and build:** Investigate a problem with `create-spike`, then implement it with `build-from-issue` once a human approves.\n- **Triage and route:** Community issues are assessed with `triage-issue`, classified, and routed into the spike-build pipeline.\n- **Security review:** `review-security-issue` produces a severity assessment and remediation plan. `fix-security-issue` implements it.\n- **Policy authoring:** `generate-sandbox-policy` creates YAML policies from plain-language requirements or API documentation.\n\nAll implementation work is human-gated — agents propose plans, humans approve, agents build. See [AGENTS.md](AGENTS.md) for the full workflow chain documentation.\n\n## Getting Help\n\n- **Questions and discussion:** [GitHub Discussions](https://github.com/NVIDIA/OpenShell/discussions)\n- **Bug reports:** [GitHub Issues](https://github.com/NVIDIA/OpenShell/issues) — use the bug report template\n- **Security vulnerabilities:** See [SECURITY.md](SECURITY.md) — do not use GitHub Issues\n- **Agent-assisted help:** Clone the repo and use the agent skills in `.agents/skills/` for self-service diagnostics\n\n## Learn More\n\n- [Full Documentation](https://docs.nvidia.com/openshell/latest/index.html) — overview, architecture, tutorials, and reference\n- [Quickstart](https://github.com/NVIDIA/OpenShell/blob/main/docs/get-started/quickstart.md) — detailed install and first sandbox walkthrough\n- [GitHub Sandbox Tutorial](https://github.com/NVIDIA/OpenShell/blob/main/docs/tutorials/github-sandbox.md) — end-to-end scoped GitHub repo access\n- [Architecture](https://github.com/NVIDIA/OpenShell/tree/main/architecture) — detailed architecture docs and design decisions\n- [Support Matrix](https://github.com/NVIDIA/OpenShell/blob/main/docs/reference/support-matrix.md) — platforms, versions, and kernel requirements\n- [Brev Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3Ap3tL55zq4a8kew1AuW0FpSLsg) — try OpenShell on cloud compute without local setup\n- [Agent Instructions](AGENTS.md) — system prompt and workflow documentation for agent contributors\n\n## Contributing\n\nOpenShell is built agent-first — your agent is your first collaborator. Before opening issues or submitting code, point your agent at the repo and let it use the skills in `.agents/skills/` to investigate, diagnose, and prototype. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full agent skills table, contribution workflow, and development setup.\n\n## License\n\nThis project is licensed under the [Apache License 2.0](https://github.com/NVIDIA/OpenShell/blob/main/LICENSE).\n","funding_links":[],"categories":["Tools","Rust","Defense \u0026 Security Controls","Sandboxing \u0026 Isolation"],"sub_categories":["Sandboxing","Agent Runtime Security \u0026 Sandboxing"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNVIDIA%2FOpenShell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNVIDIA%2FOpenShell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNVIDIA%2FOpenShell/lists"}