面向自主 AI 代理的沙箱运行时，通过声明式 YAML 策略强制执行文件系统、网络和进程约束，并支持端点绑定的凭据注入。
OpenShell 是面向自主 AI 代理的安全、私密运行时。它提供沙箱化执行环境，保护你的数据、凭据和基础设施——由声明式 YAML 策略进行治理，防止未经授权的文件访问、数据外泄和不受控制的网络活动。
OpenShell 以代理优先为设计理念。它提供用于使用和操作 OpenShell 的公共代理技能，以及面向贡献者和维护者的独立仓库感知工作流。
二进制文件（推荐）：```bash curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
安装程序默认安装最新的稳定版本。要安装特定版本，请设置 `OPENSHELL_VERSION`。还提供了一个 [`dev` 版本](https://github.com/NVIDIA/OpenShell/releases/tag/dev)，它跟踪 `main` 分支上的最新提交。
PyPI 上的 `openshell` 包仅提供 Python SDK。它不会安装 `openshell` CLI。使用 [uv](https://docs.astral.sh/uv/) 将 SDK 添加到 Python 项目：```bash
uv add openshell
Helm chart：
实验性 — Kubernetes 部署路径正在积极开发中。预计会有粗糙的边缘和破坏性变更。
从发布到 GHCR 的 OCI chart 将 OpenShell 网关部署到 Kubernetes 集群中：```bash helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart
有关可用版本、开发标签约定和配置，请参阅 [`deploy/helm/openshell/README.md`](https://github.com/nvidia/openshell/blob/main/deploy/helm/openshell/README.md)。
有关在 OpenShift 上部署 OpenShell，请参阅 [`deploy/helm/openshell/README.md#install-on-openshift`](https://github.com/nvidia/openshell/blob/main/deploy/helm/openshell/README.md#install-on-openshift)。
### 创建沙箱```bash
openshell sandbox create -- claude # or opencode, codex, copilot
沙箱容器默认包含以下工具：
更多详情请参见 https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base。
每个沙箱启动时都只有最小的出站访问权限。你可以通过一份简短的 YAML 策略来开放额外的访问权限，代理会在 HTTP 方法和路径级别强制执行该策略，而无需重启任何服务。```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"}
查看[完整演练](https://github.com/nvidia/openshell/blob/main/examples/sandbox-policy-quickstart)或运行自动化演示：```bash
bash examples/sandbox-policy-quickstart/demo.sh
OpenShell 将每个沙箱隔离在各自的容器中，并通过策略强制执行的出站路由进行管理。一个轻量级网关协调沙箱生命周期，所有出站连接都会被策略引擎拦截，策略引擎会执行以下三种操作之一：
| 组件 | 角色 |
|---|---|
| 网关 | 控制平面 API，协调沙箱生命周期并充当认证边界。 |
| 沙箱 | 隔离的运行时环境，具有容器监督和策略强制执行的出站路由。 |
| 策略引擎 | 从应用层到内核层强制执行文件系统、网络和进程约束。 |
OpenShell 运行一个网关控制平面，通过配置的计算驱动管理沙箱生命周期。支持的计算平台包括 Docker、Podman、MicroVM 和 Kubernetes。
OpenShell 在四个策略域中应用纵深防御：
| 层 |
|---|
策略是声明式的 YAML 文件。静态部分（文件系统、进程）在创建时锁定；网络策略和提供商附件可以在运行中的沙箱上更新。
代理需要凭证——API 密钥、令牌、服务账户。OpenShell 将这些作为提供商进行管理：命名的凭证包，在创建时注入沙箱。CLI 会从你的 shell 环境中自动发现已识别代理（Claude、Codex、OpenCode、Copilot）的凭证，或者你可以使用 openshell provider create 显式创建提供商。凭证永远不会泄漏到沙箱文件系统中；它们在运行时作为环境变量注入。
推理访问使用相同的提供商工作流。将支持推理的提供商附加到沙箱，调用提供商的原生端点，并在客户端中选择模型。提供商配置文件提供端点策略，并将凭证占位符绑定到授权的目标地址。
实验性 — GPU 直通在受支持的主机上可用，但仍在积极开发中。预计会有粗糙的边缘和破坏性变更。
OpenShell 可以将主机 GPU 传递到沙箱中，用于本地推理、微调或任何 GPU 工作负载。在创建沙箱时添加 --gpu：```bash
openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude
Docker 支持的 GPU 沙箱在可用时会自动选择 CDI，否则回退到 Docker 的 NVIDIA GPU 请求路径（`--gpus all`）。
**要求：** 主机上必须安装 NVIDIA 驱动程序和 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)。沙箱镜像本身必须包含适用于您工作负载的 GPU 驱动程序和库——默认的 `base` 镜像不包含。请参阅 [BYOC 示例](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container)，了解如何构建支持 GPU 的自定义沙箱镜像。
## 支持的代理
| 代理 | 来源 | 备注 |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | 开箱即用。提供程序使用 `ANTHROPIC_API_KEY`。 |
| [OpenCode](https://opencode.ai/) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | 开箱即用。提供程序使用 `OPENAI_API_KEY` 或 `OPENROUTER_API_KEY`。 |
| [Codex](https://developers.openai.com/codex) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | 开箱即用。提供程序使用 `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) | 开箱即用。提供程序使用 `GITHUB_TOKEN` 或 `COPILOT_GITHUB_TOKEN`。 |
| [OpenClaw](https://openclaw.ai/) | [NemoClaw](https://github.com/NVIDIA/NemoClaw) | 使用 NemoClaw 蓝图在 NVIDIA OpenShell 中更安全地运行 OpenClaw。 |
| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | [NemoClaw](https://github.com/NVIDIA/NemoClaw) | 使用 NemoClaw 蓝图在 NVIDIA OpenShell 中更安全地运行 Hermes Agent。 |
| [Ollama](https://ollama.com/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | 使用 `openshell sandbox create --from ollama` 启动。 |
| [Pi](https://pi.dev/) | [Community](https://github.com/NVIDIA/OpenShell-Community) | 使用 `openshell sandbox create --from pi` 启动。 |
## 关键命令
| 命令 | 描述 |
| ---------------------------------------------------------- | ----------------------------------------------- |
| `openshell sandbox create -- <agent>` | 创建沙箱并启动代理。 |
| `openshell sandbox connect [name]` | SSH 连接到正在运行的沙箱。 |
| `openshell sandbox list` | 列出所有沙箱。 |
| `openshell provider create --type [type] --from-existing` | 从环境变量创建凭据提供程序。 |
| `openshell sandbox provider attach <sandbox> <provider>` | 将提供程序附加到正在运行的沙箱。 |
| `openshell policy set <name> --policy file.yaml` | 在正在运行的沙箱上应用或更新策略。 |
| `openshell policy get <name>` | 显示活动策略。 |
| `openshell logs [name] --tail` | 流式传输沙箱日志。 |
| `openshell term` | 启动用于调试的实时终端 UI。 |
请参阅[完整文档](https://docs.nvidia.com/openshell/latest)，获取命令指南、教程和参考资料。
## 终端 UI
OpenShell 包含一个实时终端仪表板，用于监控网关、沙箱和提供程序——灵感来自 [k9s](https://k9scli.io/)。```bash
openshell term
TUI 为你提供网关和沙箱的实时、键盘驱动的视图。使用 Tab 切换面板，j/k 在列表中移动，Enter 进行选择，: 进入命令模式。网关健康状况和沙箱状态每两秒自动刷新。
使用 --from 从 OpenShell Community 目录或容器镜像创建沙箱：```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
使用本地网关所用的容器引擎进行构建。对于远程网关，请将镜像推送到网关可以拉取的注册表。
有关详细信息，请参阅 [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) 目录和 [BYOC 示例](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container)。
## 将 OpenShell 与你的 Agent 配合使用
OpenShell 为用户和运维人员提供了四项可移植技能：CLI 工作流（`openshell-cli`）、网关故障排查（`debug-openshell-cluster`）、推理故障排查（`debug-inference`）以及策略生成（`generate-sandbox-policy`）。使用 Agent Skills CLI 安装它们：```bash
npx skills add NVIDIA/OpenShell
这些公开的、可安装的技能位于 skills/ 中，并以已安装的 CLI 帮助和已发布的文档作为其事实来源。它们不需要 OpenShell 源代码检出。
OpenShell 使用它所支持的相同智能体驱动工作流进行开发。贡献者和维护者技能单独位于 .agents/skills/ 中；它们自动化 OpenShell 仓库上的工作，并且在用户安装公开技能时不会被包含：
create-spike 调查问题；由人类通过 state:accepted 或路线图排期来接受，或拒绝。被接受的工作可以继续由人类负责，或进入可选的、由人类把关的 agent:* 规划与实现工作流。triage-issue 评估社区问题。智能体确定技术有效性和影响；人类决定项目是否应采取行动以及该工作在路线图中的位置。review-security-issue 生成严重性评估和修复计划。fix-security-issue 实施该计划。sync-agent-infra、update-docs-from-commits 以及其他内部工作流保持代码、文档和智能体基础设施的一致性。智能体实现由人类指导：用户可以直接请求某个阶段，或者维护者可以使用可选的 agent:* 工作流来排队并批准规划与实现。有关完整的工作流链文档，请参阅 AGENTS.md。
npx skills add NVIDIA/OpenShell 安装公开的 OpenShell 技能rfc 标签跟踪的 RFC 提案OpenShell 以智能体优先的方式构建。问题应包含用户故事、问题陈述、影响和验收标准。影响应解释当前行为的后果以及为什么现有变通方法不够充分。功能请求还需要工作流级别的拟议设计和替代方案；错误报告则添加复现步骤、环境详细信息和相关日志。一旦工作通过项目工作流或直接请求获得授权，贡献者应使用 .agents/skills/ 中的技能来调查当前代码和行为、实施更改并进行验证。如果问题包含先前的诊断信息，请验证它们，而不是依赖它们。有关完整的智能体技能表、贡献工作流和开发设置，请参阅 CONTRIBUTING.md。
OpenShell 收集匿名遥测数据，以帮助为开发者改进项目。这些数据不用于跟踪单个用户行为。它帮助我们了解沙箱、提供者和策略工作流的总体使用情况，以便我们优先安排产品改进并与社区分享使用趋势。
在运行时通过在网关部署上设置 OPENSHELL_TELEMETRY_ENABLED=false 来禁用遥测。对于 Helm 安装，设置 server.telemetryEnabled=false。OpenShell 会将此部署设置传播到沙箱监督程序环境中，因此沙箱侧的遥测收集也会被禁用。
你也可以完全编译掉遥测功能。遥测支持是一个默认开启的 telemetry Cargo 特性，每个包含它的 crate 还定义了一个 defaults-without-telemetry 别名，涵盖所有其他默认特性。使用 --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
生成的二进制文件不包含遥测端点、遥测 HTTP 客户端和发射代码。在遥测被编译排除的情况下，网关不发射任何内容，并向其启动的沙箱报告遥测已禁用。Cargo 无法减去单个默认特性，因此 `defaults-without-telemetry` 必须与 `--no-default-features` 配合使用；单独传递它会使默认特性保持不变，并导致构建失败，而不是生成一个仍然会发射遥测的二进制文件。
网关还为其内置计算驱动暴露了独立的 Cargo 特性：`compute-driver-kubernetes`、`compute-driver-docker`、`compute-driver-podman`、`compute-driver-vm` 和 `compute-driver-mxc`。禁用默认特性集，然后仅启用目标二进制所需的驱动和遥测模式。例如：```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
常规构建通过默认的 in-tree-compute-drivers 兼容性特性保留其平台驱动集。在 Windows 上，compute-driver-mxc 选择 MXC；其他四个特性安装不受支持的驱动桩。在其他平台上，MXC 被排除在外。
遥测事件仅限于匿名操作类别和计数，例如沙箱生命周期结果、提供者配置文件分桶、策略决策计数以及聚合网络活动拒绝类别。OpenShell 遥测不会收集沙箱名称或 ID、主机名、文件路径、二进制路径、提示词、凭据、提供者名称、模型名称或用户内容。
选择退出仅适用于 OpenShell 发出的遥测数据。您配置并与 OpenShell 一起使用的第三方服务、模型提供者、推理端点、代理或工具可能拥有各自的条款和隐私惯例。
我们每两周发布一次来自此遥测数据的聚合使用趋势。请参阅社区遥测报告获取最新摘要。
本软件会自动检索、访问或与外部材料交互。这些检索到的材料不随本软件分发，仅受单独的条款、条件和许可约束。您需自行负责查找、审阅并遵守所有适用的条款、条件和许可，并针对您的具体用例验证任何检索到的材料的安全性、完整性和适用性。本软件按“原样”提供，不附带任何形式的保证。作者对任何检索到的材料不作任何陈述或保证，并且对因您使用或无法使用本软件或任何检索到的材料而产生的任何损失、损害、责任或法律后果不承担任何责任。使用本软件及检索到的材料，风险自负。
本项目根据 Apache License 2.0 许可。
| 类别 | 工具 |
|---|
| Agent | claude、opencode、codex、copilot |
| 语言 | python (3.14)、node (22) |
| 开发者 | gh、git、vim、nano |
| 网络 | ping、dig、nslookup、nc、traceroute、netstat |
| 提供商访问 | 配置文件定义的端点、二进制策略，以及针对模型 API 和其他服务的端点绑定凭证注入。 |
| 保护内容 |
|---|
| 应用时机 |
|---|
| 文件系统 | 防止在允许路径之外的读/写操作。 | 在沙箱创建时锁定。 |
| 网络 | 阻止未经授权的出站连接。 | 运行时支持热重载。 |
| 进程 | 阻止权限提升和危险的系统调用。 | 在沙箱创建时锁定。 |
| 提供商 | 授予端点绑定的凭证和网络访问权限。 | 运行时支持热重载。 |