Mrunal Patel
b4afcd8a43
* fix(cli): suppress ANSI color when stdout is not a terminal
The CLI colorized output unconditionally. owo-colors is built without
its `supports-colors` feature, so `.green()` and friends emitted escape
sequences regardless of destination, and nothing in the CLI read
NO_COLOR. Piping any command through grep or awk matched against bytes
the caller could not see; `forward list` was the case that surfaced it,
where an escape sits immediately before the STATUS word and defeats a
pattern anchored on whitespace.
Add a `color` module holding a process-wide switch resolved once in
run_async, before any output. Command modules import its `Colorize`
trait in place of `OwoColorize`; the method names match, so the ~450
call sites are unchanged, but each consults the switch when it renders
and delegates to owo-colors so the escape bytes stay identical. The two
traits collide by design: importing both in one module is an ambiguity
error, which keeps unconditional coloring from returning.
owo-colors is not the only styled path, and the rest each carry their
own default, so the switch governs them too:
- tracing_subscriber formats with ANSI on, does no terminal detection,
and writes to stdout, so `openshell -v ... | ...` leaked escapes the
same way the tables did. It now takes the setting via with_ansi.
- indicatif and dialoguer both style through console, which has its
own detection but cannot learn about --color. Overriding console's
global switch covers every progress bar and prompt rather than the
specific ones constructed today. Both the stdout and stderr switches
are set, since prompts and progress bars draw to stderr.
- miette renders errors through its own handler, likewise unaware of
--color, so init installs one built from the setting.
Resolution order: `--color always|never`, then NO_COLOR, then
CLICOLOR_FORCE, then whether stdout is a terminal. The decision is made
against stdout even for stderr text, since stdout is what gets parsed;
`--color always` restores styling when redirecting.
Padding is unaffected — the format spec is forwarded to the inner
Display, so widths measure text rather than text plus escapes.
Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
* fix(cli): resolve color per output stream
Review feedback on #3026.
Resolving one answer from stdout and handing it to every library meant a
redirected stream inherited the other stream's terminal check. Running
`openshell ... 2> build.log` from a terminal wrote escapes into the log,
because console's stderr switch and miette's handler were both given
stdout's answer. That is worse than the behavior before this branch,
where both libraries did their own per-stream detection.
Resolve `auto` separately for stdout and stderr and hand each library
the answer for the stream it writes to: tracing and console's stdout
switch get stdout, miette and console's stderr switch get stderr. The
owo-colors wrapper is the exception, since its call sites are split
across println! and eprintln! and a Painted value cannot tell which
macro will consume it; it styles only when both streams accept escapes,
erring toward plain text rather than risking a redirected stream.
Existing tests could not catch this: Command::output gives both streams
pipes, so a per-stream decision and a single stdout-derived one look
identical. Add a test that puts stdout on a pty and stderr on a pipe,
which fails when stderr is handed stdout's answer.
Replace CLICOLOR_FORCE with FORCE_COLOR. The clicolors spec does not say
how to treat `0`, and implementations that special-case it disagree with
force-color.org, which keys on presence and non-emptiness only. Using
FORCE_COLOR gives it the same rule as NO_COLOR: set and non-empty means
yes, whatever the value. Nothing depended on CLICOLOR_FORCE, which was
introduced earlier on this branch and never released.
Carry the whole style in an owo_colors::Style rather than dispatching a
local enum through a six-arm match, and merge styles when chaining so
`x.green().bold()` emits one `\x1b[32;1m...\x1b[0m` instead of nesting
two wrappers. No call site styles already-styled text, so merging is
safe; the emitted bytes are shorter and there is a single reset.
Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
---------
Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
OpenShell 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.
OpenShell is built agent-first. The project ships with agent skills for everything from gateway troubleshooting to policy generation, and we expect contributors to use them.
Quickstart
Prerequisites
- A supported host — Linux, macOS (Apple Silicon), or Windows with WSL 2 (experimental).
- A local runtime — Docker, Podman, or host virtualization enabled for MicroVM-backed sandboxes.
Install
Binary (recommended):
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
The installer installs the latest stable release by default. To install a specific version, set OPENSHELL_VERSION. A dev release is also available that tracks the latest commit on main.
The openshell package on PyPI provides the Python SDK only. It does not install the openshell CLI. Add the SDK to a Python project with uv:
uv add openshell
Helm chart:
Experimental — the Kubernetes deployment path is under active development. Expect rough edges and breaking changes.
Deploy the OpenShell gateway into a Kubernetes cluster from the OCI chart published to GHCR:
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart
See deploy/helm/openshell/README.md for available versions, dev tag conventions, and configuration.
For deploying OpenShell on OpenShift, see deploy/helm/openshell/README.md#install-on-openshift.
Create a sandbox
openshell sandbox create -- claude # or opencode, codex, copilot
The sandbox container includes the following tools by default:
| Category | Tools |
|---|---|
| Agent | claude, opencode, codex, copilot |
| Language | python (3.14), node (22) |
| Developer | gh, git, vim, nano |
| Networking | ping, dig, nslookup, nc, traceroute, netstat |
For more details see https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base.
See network policy in action
Every 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.
# 1. Create a sandbox (starts with minimal outbound access)
openshell sandbox create
# 2. Inside the sandbox — blocked
sandbox$ curl -sS https://api.github.com/zen
curl: (56) Received HTTP code 403 from proxy after CONNECT
# 3. Back on the host — apply a read-only GitHub API policy
sandbox$ exit
openshell policy set demo --policy examples/sandbox-policy-quickstart/policy.yaml --wait
# 4. Reconnect — GET allowed, POST blocked by L7
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"}
See the full walkthrough or run the automated demo:
bash examples/sandbox-policy-quickstart/demo.sh
How It Works
OpenShell 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:
- Allows — the destination and binary match a policy block.
- Routes for inference — strips caller credentials, injects backend credentials, and forwards to the managed model.
- Denies — blocks the request and logs it.
| Component | Role |
|---|---|
| Gateway | Control-plane API that coordinates sandbox lifecycle and acts as the auth boundary. |
| Sandbox | Isolated runtime with container supervision and policy-enforced egress routing. |
| Policy Engine | Enforces filesystem, network, and process constraints from application layer down to kernel. |
| Privacy Router | Privacy-aware LLM routing that keeps sensitive context on sandbox compute. |
OpenShell runs a gateway control plane that manages sandbox lifecycle through a configured compute driver. Supported compute platforms include Docker, Podman, MicroVM, and Kubernetes.
Protection Layers
OpenShell applies defense in depth across four policy domains:
| Layer | What it protects | When it applies |
|---|---|---|
| Filesystem | Prevents reads/writes outside allowed paths. | Locked at sandbox creation. |
| Network | Blocks unauthorized outbound connections. | Hot-reloadable at runtime. |
| Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. |
| Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. |
Policies 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.
Providers
Agents 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.
GPU Support (Experimental)
Experimental — GPU passthrough works on supported hosts but is under active development. Expect rough edges and breaking changes.
OpenShell can pass host GPUs into sandboxes for local inference, fine-tuning, or any GPU workload. Add --gpu when creating a sandbox:
openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude
Docker-backed GPU sandboxes auto-select CDI when available and otherwise fall back to Docker's NVIDIA GPU request path (--gpus all).
Requirements: NVIDIA drivers and the NVIDIA Container Toolkit 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 for building a custom sandbox image with GPU support.
Supported Agents
| Agent | Source | Notes |
|---|---|---|
| Claude Code | base |
Works out of the box. Provider uses ANTHROPIC_API_KEY. |
| OpenCode | base |
Works out of the box. Provider uses OPENAI_API_KEY or OPENROUTER_API_KEY. |
| Codex | base |
Works out of the box. Provider uses OPENAI_API_KEY. |
| GitHub Copilot CLI | base |
Works out of the box. Provider uses GITHUB_TOKEN or COPILOT_GITHUB_TOKEN. |
| OpenClaw | NemoClaw | Run OpenClaw more securely inside NVIDIA OpenShell with managed inference using NemoClaw. |
| Hermes Agent | NemoClaw | Run Hermes Agent more securely inside NVIDIA OpenShell with managed inference using NemoClaw. |
| Ollama | Community | Launch with openshell sandbox create --from ollama. |
| Pi | Community | Launch with openshell sandbox create --from pi. |
Key Commands
| Command | Description |
|---|---|
openshell sandbox create -- <agent> |
Create a sandbox and launch an agent. |
openshell sandbox connect [name] |
SSH into a running sandbox. |
openshell sandbox list |
List all sandboxes. |
openshell provider create --type [type] --from-existing |
Create a credential provider from env vars. |
openshell policy set <name> --policy file.yaml |
Apply or update a policy on a running sandbox. |
openshell policy get <name> |
Show the active policy. |
openshell inference set --provider <p> --model <m> |
Configure the inference.local endpoint. |
openshell logs [name] --tail |
Stream sandbox logs. |
openshell term |
Launch the real-time terminal UI for debugging. |
See the full documentation for command guides, tutorials, and reference material.
Terminal UI
OpenShell includes a real-time terminal dashboard for monitoring gateways, sandboxes, and providers — inspired by k9s.
openshell term
The TUI gives you a live, keyboard-driven view of your gateway and sandboxes. Navigate with Tab to switch panels, j/k to move through lists, Enter to select, and : for command mode. Gateway health and sandbox status auto-refresh every two seconds.
Community Sandboxes and BYOC
Use --from to create sandboxes from the OpenShell Community catalog, a local directory, or a container image:
openshell sandbox create --from gemini # community catalog
openshell sandbox create --from ./my-sandbox-dir # local Dockerfile
openshell sandbox create --from registry.io/img:v1 # container image
See the OpenShell Community catalog and the BYOC example for details.
Explore with Your Agent
Clone 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.
git clone https://github.com/NVIDIA/OpenShell.git # or git@github.com:NVIDIA/OpenShell.git
cd OpenShell
# Point your agent here — it will discover the skills in .agents/skills/ automatically
Your agent can load skills for CLI usage (openshell-cli), gateway troubleshooting (debug-openshell-cluster), inference troubleshooting (debug-inference), policy generation (generate-sandbox-policy), and more. See CONTRIBUTING.md for the full skills table.
Built With Agents
OpenShell is developed using the same agent-driven workflows it enables. The .agents/skills/ directory contains workflow automation that powers the project's development cycle:
- Spike and build: Investigate a problem with
create-spike; a human accepts it withstate:acceptedor roadmap placement, or declines it. Accepted work can remain human-owned or enter the optional, human-gatedagent:*planning and implementation workflow. - Triage and route: Community issues are assessed with
triage-issue. Agents establish technical validity and impact; humans decide whether the project should act and where the work sits on the roadmap. - Security review:
review-security-issueproduces a severity assessment and remediation plan.fix-security-issueimplements it. - Policy authoring:
generate-sandbox-policycreates YAML policies from plain-language requirements or API documentation.
All agent implementation work is human-gated: maintainers explicitly request a plan, agents propose it, maintainers approve it, and agents build. See AGENTS.md for the full workflow chain documentation.
Getting Help
- Questions and discussion: GitHub Discussions
- Bug reports: GitHub Issues — use the bug report template
- Security vulnerabilities: See SECURITY.md — do not use GitHub Issues
- Agent-assisted help: Clone the repo and use the agent skills in
.agents/skills/for self-service diagnostics
Learn More
- Full Documentation — overview, architecture, tutorials, and reference
- Quickstart — detailed install and first sandbox walkthrough
- GitHub Sandbox Tutorial — end-to-end scoped GitHub repo access
- Architecture — detailed architecture docs and design decisions
- Roadmap — planned work and project priorities
- RFC Board — RFC proposals tracked on the OpenShell Roadmap with the
rfclabel - Support Matrix — platforms, versions, and kernel requirements
- Brev Launchable — try OpenShell on cloud compute without local setup
- Agent Instructions — system prompt and workflow documentation for agent contributors
Contributing
OpenShell is built agent-first. Issues should include a user story, problem statement, impact, and acceptance criteria. The impact should explain the consequences of the current behavior and why existing workarounds are insufficient. Feature requests also require a workflow-level proposed design and alternatives; bug reports add reproduction steps, environment details, and relevant logs. Once maintainers accept work, contributors should use the skills in .agents/skills/ to investigate the current code and behavior, implement the change, and verify it. If an issue contains earlier diagnostics, verify them rather than relying on them. See CONTRIBUTING.md for the full agent skills table, contribution workflow, and development setup.
Telemetry
OpenShell collects anonymous telemetry to help improve the project for developers. This data is not used to track individual user behavior. It helps us understand aggregate usage of sandbox, provider, and policy workflows so we can prioritize product improvements and share usage trends with the community.
Disable telemetry at runtime by setting OPENSHELL_TELEMETRY_ENABLED=false on the gateway deployment. For Helm installs, set server.telemetryEnabled=false. OpenShell propagates this deployment setting into sandbox supervisor environments so sandbox-side telemetry collection is disabled as well.
You can also compile telemetry out entirely. Telemetry support is a default-on telemetry Cargo feature, and each crate that carries it also defines a defaults-without-telemetry alias covering every other default feature. Build telemetry-free artifacts with --no-default-features --features defaults-without-telemetry:
cargo build --release -p openshell-server --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
The resulting binaries contain no telemetry endpoint, no telemetry HTTP client, and no emission code. With telemetry compiled out, the gateway emits nothing and reports telemetry disabled to the sandboxes it launches. Cargo has no way to subtract a single default feature, so defaults-without-telemetry must be paired with --no-default-features; passing it on its own leaves the defaults in place and fails the build rather than producing a binary that still emits.
Telemetry events are limited to anonymous operational categories and counts, such as sandbox lifecycle outcomes, provider profile buckets, policy decision counts, and aggregate network activity denial categories. OpenShell telemetry does not collect sandbox names or IDs, hostnames, file paths, binary paths, prompts, credentials, provider names, model names, or user content.
Opting out applies only to telemetry emitted by OpenShell. Third-party services, model providers, inference endpoints, agents, or tools that you configure and use with OpenShell may have their own terms and privacy practices.
We publish aggregate usage trends from this telemetry every two weeks. See the community telemetry reports for the latest summary.
Notice and Disclaimer
This software automatically retrieves, accesses or interacts with external materials. Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses. You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case. This software is provided "AS IS", without warranty of any kind. The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials. Use this software and the retrieved materials at your own risk.
License
This project is licensed under the Apache License 2.0.