John T. Myers
fcf12dff62
* feat(tui): support light terminal backgrounds with adaptive theme Replace the hardcoded dark-only color constants in theme.rs with a runtime Theme struct that has dark() and light() factory constructors. The active theme is stored on App and threaded through all draw functions, enabling the TUI to render correctly on both dark and light terminal backgrounds. - Add Theme struct with 16 semantic style fields and ThemeMode enum - Detect terminal background via COLORFGBG env var at startup - Add --theme dark|light|auto CLI flag and OPENSHELL_THEME env var - Migrate all 499 styles:: references across 11 UI files to app.theme - Clean up 9 inline Style constructions that bypassed the theme system - Add unit tests verifying dark/light palettes and legacy regression Closes #264 * fix(tui): use OSC 11 query for reliable light/dark terminal detection Replace COLORFGBG env var heuristic with terminal-colorsaurus crate, which sends an OSC 11 query to read the actual background color. This fixes auto-detection in iTerm2 and other terminals that don't set COLORFGBG.
OpenShell
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.
Quickstart
Prerequisites
- Docker — Docker Desktop (or a Docker daemon) must be running.
Install
Binary (recommended):
curl -fsSL https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
The install script auto-detects your platform (Linux x86_64, Linux aarch64, macOS Apple Silicon) and places the openshell binary in /usr/local/bin. See the releases page for manual download options.
From PyPI (requires uv):
uv tool install -U openshell
Create a sandbox
openshell sandbox create -- claude # or opencode, codex, --from openclaw
A gateway cluster is created automatically on first use. To deploy on a remote host instead, use openshell gateway start --remote user@host.
The sandbox container includes the following tools by default:
| Category | Tools |
|---|---|
| Agent | claude, opencode, codex |
| Language | python (3.12), node (22) |
| Developer | gh, git, vim, nano |
| Networking | ping, dig, nslookup, nc, traceroute, netstat |
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.
Supported Agents
| Agent | Source | Notes |
|---|---|---|
| Claude Code | Built-in | Works out of the box. Requires ANTHROPIC_API_KEY. |
| OpenCode | Built-in | Works out of the box. Requires OPENAI_API_KEY or OPENROUTER_API_KEY. |
| Codex | Built-in | Works out of the box. Requires OPENAI_API_KEY. |
| OpenClaw | Community | Launch with openshell sandbox create --from openclaw. |
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.
Under the hood, the gateway runs as a K3s Kubernetes cluster inside Docker — no separate K8s install required.
| 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. |
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 sandbox delete <name> |
Delete a sandbox. |
openshell provider create --type claude --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 CLI reference for all commands, flags, and environment variables.
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 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.
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 openclaw # community catalog
openshell sandbox create --from ./my-sandbox-dir # local Dockerfile
openshell sandbox create --from registry.io/img:v1 # container image
See the community sandboxes catalog and the BYOC example for details.
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
- Support Matrix — platforms, versions, and kernel requirements
Contributing
See CONTRIBUTING.md for building from source and contributing to OpenShell.
License
This project is licensed under the Apache License 2.0.