NVIDIA/OpenShell

# NVIDIA OpenShell [](https://github.com/NVIDIA/OpenShell/blob/main/LICENSE) [](https://pypi.org/project/openshell/) [](SECURITY.md) [](https://docs.nvidia.com/openshell/latest/index.html) [](https://docs.nvidia.com/openshell/latest/about/release-notes.html) OpenShell 是专为自主 AI agent 打造的安全、私密运行时。它提供了沙盒化的执行环境，以保护您的数据、凭证和基础设施——通过声明式 YAML 策略进行治理，从而防止未经授权的文件访问、数据泄露和不受控制的网络活动。 OpenShell 采用 agent 优先的构建理念。该项目自带了涵盖从网关故障排查到策略生成等各项功能的 agent 技能，我们也鼓励贡献者使用这些技能。 ## 快速入门 ### 前置条件 - **受支持的主机** — macOS、带有 WSL 2 的 Windows 或 Linux。 - **本地运行时** — Docker、Podman，或为基于 MicroVM 的沙盒启用了主机虚拟化。 ### 安装 **二进制文件（推荐）：** ``` curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh ``` **通过 PyPI 安装（需要 [uv](https://docs.astral.sh/uv/)）：** ``` uv tool install -U openshell ``` 这两种方法默认都会安装最新的稳定版本。要安装特定版本，请设置 `OPENSHELL_VERSION`（二进制文件）或使用 `uv tool install openshell==` 锁定版本。我们还提供了一个追踪 `main` 分支最新提交的 [`dev` 版本](https://github.com/NVIDIA/OpenShell/releases/tag/dev)。 **Helm chart：** 将 OpenShell 网关部署到 Kubernetes 集群中，使用发布到 GHCR 的 OCI chart： ``` helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart ``` 有关可用版本、开发标签约定和配置，请参阅 [`deploy/helm/openshell/README.md`](deploy/helm/openshell/README.md)。 有关在 OpenShift 上部署 OpenShell 的信息，请参阅 [`deploy/helm/openshell/README.md#install-on-openshift`](deploy/helm/openshell/README.md#install-on-openshift)。 ### 创建沙盒 ``` openshell sandbox create -- claude # or opencode, codex, copilot ``` 沙盒容器默认包含以下工具： | 类别 | 工具 | | -------- | -------------------------------------------------------- | | Agent | `claude`, `opencode`, `codex`, `copilot` | | 语言 | `python` (3.13), `node` (22) | | 开发 | `gh`, `git`, `vim`, `nano` | | 网络 | `ping`, `dig`, `nslookup`, `nc`, `traceroute`, `netstat` | 有关更多详细信息，请参阅 https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base。 ### 查看网络策略的实际运行情况 每个沙盒在启动时都具有**最小的出站访问权限**。您可以通过一段简短的 YAML 策略来开放额外的访问权限，代理将在 HTTP 方法和路径级别强制执行该策略，而无需重启任何内容。 ``` # 1. 创建 sandbox（启动时具有最小出站访问权限） openshell sandbox create # 2. 在 sandbox 内部 — 已阻止 sandbox$ curl -sS https://api.github.com/zen curl: (56) Received HTTP code 403 from proxy after CONNECT # 3. 回到 host — 应用只读 GitHub API policy sandbox$ exit openshell policy set demo --policy examples/sandbox-policy-quickstart/policy.yaml --wait # 4. 重新连接 — GET 被允许，POST 被 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"} ``` 查看[完整演练](examples/sandbox-policy-quickstart/)或运行自动演示： ``` bash examples/sandbox-policy-quickstart/demo.sh ``` ## 工作原理 OpenShell 将每个沙盒隔离在各自的容器中，并强制执行出口路由策略。一个轻量级网关负责协调沙盒的生命周期，每个出站连接都会被策略引擎拦截，该引擎会执行以下三种操作之一： - **允许** — 目标和二进制文件与策略块匹配。 - **路由以进行推理** — 剥离调用者凭证，注入后端凭证，并转发到托管模型。 - **拒绝** — 阻止请求并记录日志。 | 组件 | 角色 | | -------------- | -------------------------------------------------------------------------------------------- | | **网关** | 控制平面 API，负责协调沙盒生命周期并充当身份验证边界。 | | **沙盒** | 隔离的运行时，带有容器监督和强制执行策略的出口路由。 | | **策略引擎** | 从应用层向下到内核，强制执行文件系统、网络和进程约束。 | | **隐私路由器** | 具备隐私意识的 LLM 路由，将敏感上下文保留在沙盒计算环境中。 | OpenShell 运行网关控制平面，通过配置的计算驱动程序管理沙盒的生命周期。支持的计算平台包括 Docker、Podman、MicroVM 和 Kubernetes。 ## 保护层 OpenShell 在四个策略领域应用了纵深防御： | 层级 | 保护内容 | 应用时机 | | -------- | -------------------------------------------- | ------------------------ | | 文件系统 | 防止在允许的路径之外进行读/写操作。 | 在创建沙盒时锁定。 | | 网络 | 阻止未经授权的出站连接。 | 可在运行时热重载。 | | 进程 | 阻止权限升级和危险的系统调用。 | 在创建沙盒时锁定。 | | 推理 | 将模型 API 调用重新路由到受控后端。 | 可在运行时热重载。 | 策略是声明式的 YAML 文件。静态部分（文件系统、进程）在创建时被锁定；动态部分（网络、推理）可以在运行的沙盒上通过 `openshell policy set` 进行热重载。 ## 提供商 Agent 需要凭证——API 密钥、令牌、服务账户。OpenShell 将这些作为**提供商**进行管理：在创建时注入到沙盒中的命名凭证包。CLI 会从您的 shell 环境中自动发现已识别 agent（Claude、Codex、OpenCode、Copilot）的凭证，或者您可以使用 `openshell provider create` 显式创建提供商。凭证绝不会泄漏到沙盒文件系统中；它们会在运行时作为环境变量注入。 ## GPU 支持（实验性） OpenShell 可以将主机 GPU 传递到沙盒中，用于本地推理、微调或任何 GPU 工作负载。在创建沙盒时添加 `--gpu`： ``` openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude ``` 基于 Docker 的 GPU 沙盒在可用时会自动选择 CDI，否则会回退到 Docker 的 NVIDIA GPU 请求路径（`--gpus all`）。对于名称中带有 `gpu` 的社区镜像，GPU 意图也会被自动推断。 **要求：** 主机上必须安装 NVIDIA 驱动程序和 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)。沙盒镜像本身必须包含适合您工作负载的 GPU 驱动程序和库——默认的 `base` 镜像不包含。有关构建带有 GPU 支持的自定义沙盒镜像，请参阅 [BYOC 示例](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container)。 ## 支持的 Agent | Agent | 来源 | 备注 | | ------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | [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/) | [社区](https://github.com/NVIDIA/OpenShell-Community) | 使用 `openshell sandbox create --from openclaw` 启动。 | | [Ollama](https://ollama.com/) | [社区](https://github.com/NVIDIA/OpenShell-Community) | 使用 `openshell sandbox create --from ollama` 启动。 | ## 关键命令 | 命令 | 描述 | | ---------------------------------------------------------- | ----------------------------------------------- | | `openshell sandbox create -- ` | 创建沙盒并启动 agent。 | | `openshell sandbox connect [name]` | SSH 连接到正在运行的沙盒。 | | `openshell sandbox list` | 列出所有沙盒。 | | `openshell provider create --type [type]] --from-existing` | 从环境变量创建凭证提供商。 | | `openshell policy set --policy file.yaml` | 在正在运行的沙盒上应用或更新策略。 | | `openshell policy get ` | 显示活动的策略。 | | `openshell inference set --provider

--model ` | 配置 `inference.local` 端点。 | | `openshell logs [name] --tail` | 流式传输沙盒日志。 | | `openshell term` | 启动用于调试的实时终端 UI。 | 有关命令指南、教程和参考材料，请参阅[完整文档](https://docs.nvidia.com/openshell/latest)。 ## 终端 UI OpenShell 包含一个实时终端仪表板，用于监控网关、沙盒和提供商——灵感来自 [k9s](https://k9scli.io/)。 ``` openshell term ```

TUI 为您提供了一个实时的、键盘驱动的网关和沙盒视图。使用 `Tab` 切换面板，`j`/`k` 在列表中移动，`Enter` 进行选择，以及 `:` 进入命令模式。网关健康状态和沙盒状态每两秒自动刷新一次。 ## 社区沙盒与 BYOC 使用 `--from` 从 [OpenShell 社区](https://github.com/NVIDIA/OpenShell-Community)目录、本地目录或容器镜像创建沙盒： ``` 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 ``` 有关详细信息，请参阅[社区沙盒](https://docs.nvidia.com/openshell/latest/sandboxes/community-sandboxes)目录和 [BYOC 示例](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container)。 ## 使用您的 Agent 进行探索 克隆该仓库并将您的编码 agent 指向它。该项目包含能够回答问题、引导您完成工作流程以及诊断问题的 agent 技能——无需提交 issue。 ``` git clone https://github.com/NVIDIA/OpenShell.git # or git@github.com:NVIDIA/OpenShell.git cd OpenShell # 将你的 agent 指向此处 — 它将自动发现 .agents/skills/ 中的 skills ``` 您的 agent 可以加载用于 CLI 使用（`openshell-cli`）、网关故障排查（`debug-openshell-cluster`）、推理故障排查（`debug-inference`）、策略生成（`generate-sandbox-policy`）等方面的技能。有关完整的技能表，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 使用 Agent 构建 OpenShell 是使用它所支持的相同 agent 驱动工作流进行开发的。`.agents/skills/` 目录包含为项目开发周期提供支持的工作流自动化： - **探索与构建：** 使用 `create-spike` 调查问题，然后在人工批准后使用 `build-from-issue` 实施它。 - **分流与路由：** 使用 `triage-issue` 评估社区问题，对其进行分类，并将其路由到 spike-build 管道中。 - **安全审查：** `review-security-issue` 生成严重性评估和修复计划。`fix-security-issue` 负责实施。 - **策略编写：** `generate-sandbox-policy` 根据自然语言需求或 API 文档创建 YAML 策略。 所有的实施工作都由人工把控——agent 提出计划，人类批准，agent 构建。有关完整的工作流链文档，请参阅 [AGENTS.md](AGENTS.md)。 ## 获取帮助 - **问题和讨论：** [GitHub Discussions](https://github.com/NVIDIA/OpenShell/discussions) - **错误报告：** [GitHub Issues](https://github.com/NVIDIA/OpenShell/issues) — 请使用错误报告模板 - **安全漏洞：** 参阅 [SECURITY.md](SECURITY.md) — 请勿使用 GitHub Issues - **Agent 辅助帮助：** 克隆该仓库并使用 `.agents/skills/` 中的 agent 技能进行自助诊断 ## 了解更多 - [完整文档](https://docs.nvidia.com/openshell/latest/index.html) — 概述、架构、教程和参考 - [快速入门](https://docs.nvidia.com/openshell/latest/get-started/quickstart) — 详细的安装和第一个沙盒演练 - [GitHub 沙盒教程](https://docs.nvidia.com/openshell/latest/tutorials/github-sandbox) — 端到端的作用域内 GitHub 仓库访问 - [架构](https://github.com/NVIDIA/OpenShell/tree/main/architecture) — 详细的架构文档和设计决策 - [路线图](https://github.com/orgs/NVIDIA/projects/233) — 计划中的工作和项目优先级 - [支持矩阵](https://docs.nvidia.com/openshell/latest/reference/support-matrix) — 平台、版本和内核要求 - [Brev Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3Ap3tL55zq4a8kew1AuW0FpSLsg) — 无需本地设置即可在云计算上试用 OpenShell - [Agent 指示](AGENTS.md) — 面向 agent 贡献者的系统提示和工作流文档 ## 贡献 OpenShell 采用 agent 优先的构建方式——您的 agent 是您的第一协作者。在提出问题或提交代码之前，请将您的 agent 指向该仓库，让它使用 `.agents/skills/` 中的技能进行调查诊断和制作原型。有关完整的 agent 技能表、贡献工作流和开发设置，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 通知与免责声明 本软件会自动检索、访问或与外部材料进行交互。这些检索到的材料不随本软件一起分发，完全受单独的条款、条件和许可证的约束。您需全权负责查找、审查并遵守所有适用的条款、条件和许可证，并验证任何检索到的材料对于您特定用例的安全性、完整性和适用性。本软件按“原样”提供，不提供任何形式的保证。作者不对任何检索到的材料作出任何陈述或保证，并且对于您因使用或无法使用本软件或任何检索到的材料而造成的任何损失、损害、责任或法律后果，不承担任何责任。使用本软件和检索到的材料的风险由您自行承担。 ## 许可证 本项目基于 [Apache License 2.0](https://github.com/NVIDIA/OpenShell/blob/main/LICENSE) 授权。

标签：AI代理, Docker, Helm, JSONLines, MicroVM, NIDS, Podman, PyPI, Python, Streamlit, YAML, 人工智能, 内存分配, 声明式策略, 子域名突变, 安全库, 安全沙箱, 安全防御评估, 容器化, 开源, 微虚拟机, 无后门, 用户模式Hook绕过, 策略控制, 系统运维, 网关, 网络安全, 网络安全, 网络安全审计, 自主智能体, 访问控制, 请求拦截, 运行环境, 逆向工具, 通知系统, 隐私保护, 隐私保护, 零信任