让 AI 在沙箱里干活,权限由你掌控
让 AI 在沙箱里工作,明确它能读写哪些文件、访问哪些网络。NVIDIA OpenShell 在 Agent 外部执行权限策略,将凭据用于配置允许的端点,并让你决定是否批准新增网络访问。
前置要求
- Docker Desktop / Docker Engine >= 28.0
- Git
- OPENROUTER_API_KEY
概览
你会得到什么
- 通过文件、网络和进程策略约束 Agent 的沙箱运行环境。
- 仅在配置授权的端点使用模型服务等外部服务的凭据。
- 沙箱运行期间可查看、批准或拒绝的新增网络访问建议。
适用场景
- 运行编程 Agent,明确项目文件和外部服务的访问范围。
- 将访问策略纳入版本管理,查看被拒绝的请求。
教程
先看懂它能管什么
让 AI 改代码,通常也要允许它读文件、运行命令和联网。OpenShell 把 Agent 放进独立沙箱,再由运行时执行访问策略,让权限范围落实到实际请求上。
| 你关心什么 | OpenShell 怎样控制 |
|---|---|
| AI 能读写哪些文件 | 文件策略限定沙箱内允许访问的路径 |
| AI 能访问哪些服务 | 网络规则限定目标地址、调用程序及可用请求 |
| 模型 API Key 怎样使用 | Provider 保存凭据,按配置在授权端点使用 |
接下来用 OpenCode 和 OpenRouter 跑通一个例子:让 AI 为小项目编写 README,再学习如何处理被拦截的联网请求。文件和进程策略在创建沙箱时确定;网络规则可在运行期间更新。
跑通第一个 AI 沙箱
准备本地环境
本教程使用 OpenShell 0.1.5 + Docker。准备 Git、运行中的 Docker Desktop 或 Docker Engine 28.0+,以及 OpenRouter API Key。
支持的平台包括 Linux x86_64 / arm64、Apple Silicon Mac;Windows 的 WSL 2 + Docker Desktop 路线为实验性支持。Linux 沙箱需要启用 Landlock ABI 3(通常为 Linux 6.2+),以及所需的 seccomp 能力;完整条件见官方支持矩阵。
-
在宿主机终端安装并检查连接:
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/v0.1.5/install.sh | OPENSHELL_VERSION=v0.1.5 sh openshell status安装器安装 CLI、策略检查器和本地网关。
status应能返回网关状态;连接失败时,先按安装文档检查网关服务。 -
配置模型服务。OpenRouter 是本例的模型 API 服务;Provider 是 OpenShell 保存其凭据与访问配置的对象。在同一个宿主机终端执行,先替换 API Key:
export OPENROUTER_API_KEY='替换为你的 OpenRouter API Key' # 导入 OpenCode 访问 OpenRouter 的配置 openshell profile import \ --url https://raw.githubusercontent.com/NVIDIA/OpenShell/v0.1.5/providers/openrouter.yaml # 从当前环境读取 API Key,创建名为 openrouter 的 Provider openshell provider create --name openrouter --type openrouter --from-existing该配置允许镜像中的
/usr/local/bin/opencode访问openrouter.ai。创建 Provider 成功后,下一步用名称openrouter将它附加到沙箱。
启动 OpenCode
在宿主机终端 A 中执行:
openshell sandbox create \
--name my-agent \
--from ghcr.io/anomalyco/opencode:latest \
--provider openrouter \
-- opencode -m openrouter/nvidia/nemotron-3.5-lightning:free
这采用官方首个 Agent 示例的镜像和模型路线。启动后应看到 OpenCode 界面;保持这个终端打开,后面在这里给 AI 发任务。官方例子使用 OpenRouter 的免费模型,模型列表可用镜像内的 opencode models openrouter 查看。
--from 选择装有 Agent 的镜像。默认 Ubuntu 镜像只提供基础系统,运行 OpenCode 要使用上面的 OpenCode 镜像。
让 AI 完成一个小任务
传入示例项目
-
在宿主机另开终端 B,创建一个独立的小项目:
mkdir greeting-demo cd greeting-demo git init cat > main.py <<'PY' def greet(name): return f"Hello, {name}!" if __name__ == "__main__": print(greet("Ada")) PY cd .. -
仍在终端 B,将目录传入正在运行的沙箱:
openshell sandbox upload my-agent ./greeting-demo未指定目标路径时,上传位置是沙箱工作目录,目录名
greeting-demo会保留。这里先启动沙箱再上传,避免 AI 在文件传完之前就开始读取。
编写并取回 README
-
回到终端 A 的 OpenCode 界面,发送下面的任务。这是本站为教学编写的练习请求:
读取当前工作目录下 greeting-demo/main.py。 在 greeting-demo/README.md 中说明程序用途、函数输入与输出、运行方式及预期输出。 根据源码说明即可,不安装依赖,不修改 main.py。 完成后列出新增的文件。 -
AI 完成后,在宿主机终端 B 中取回并查看文件:
openshell sandbox download my-agent greeting-demo/README.md ./greeting-demo/README.md cat ./greeting-demo/README.mdREADME 应说明
greet(name)返回问候语,直接运行程序时打印Hello, Ada!。核对说明与源码是否一致,比只看“任务完成”更有用。
遇到联网拦截,按需放行
以后给 Agent 增加查文档、下载依赖等任务时,可能遇到新地址被拒绝。OpenShell 会记录拒绝,并为新增访问生成规则建议。
-
在宿主机终端 B 中查看日志和待批准建议:
openshell logs my-agent --since 5m --source sandbox openshell rule get my-agent --status pending关注目标域名、端口和发起请求的程序。前面的 README 任务不需要联网,列表为空时可以直接进入下一节。
-
若有与当前任务相符的建议,将下面的
<chunk-id>替换为列表中的实际 ID,再批准:openshell rule approve my-agent --chunk-id <chunk-id>不需要的访问则用拒绝命令,填写实际理由:
openshell rule reject my-agent --chunk-id <chunk-id> --reason "当前任务不需要此访问" -
批准后回到 OpenCode,让 AI 重试刚才被拦截的操作。网络规则会在运行期间生效,无需重启沙箱。
这里学到的判断是:根据任务批准具体访问,而不是遇到报错就扩大整个沙箱的联网范围。
只允许读取,拦截写入
只允许访问某个域名还不够细时,可以进一步区分读取与写入。下面用一个独立的 curl 沙箱观察变化,沿用官方网络策略教程的规则写法。
准备带 curl 的镜像
在宿主机终端 B 中执行:
mkdir openshell-policy-demo
cd openshell-policy-demo
cat > Dockerfile <<'DOCKER'
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
&& rm -rf /var/lib/apt/lists/*
RUN mkdir -p /workspace && chown 1000:1000 /workspace
USER 1000:1000
WORKDIR /workspace
DOCKER
docker build -t openshell-curl-demo:local .
openshell sandbox create --name api-demo --from openshell-curl-demo:local --no-auto-providers
Docker 在构建时安装 curl;沙箱创建后使用已准备好的镜像。命令结束后,终端 B 会进入 api-demo 沙箱终端,保持它打开。
先观察拒绝,再允许读取
-
在终端 B 的沙箱内请求 GitHub API:
curl -sS https://api.github.com/zen在新本地网关的默认网络策略下,这个地址尚未获准,请求应被拦截。
-
另开宿主机终端 C,只允许
/usr/bin/curl读取这个服务:openshell policy update api-demo \ --rule-name github_api \ --binary /usr/bin/curl \ --add-endpoint api.github.com:443:read-only:rest:enforce \ --waitread-only允许 GET、HEAD、OPTIONS;rest检查 HTTP 请求;enforce拦截不符合规则的请求。这条命令只修改网络规则。 -
回到终端 B 的沙箱内,比较同一地址的 GET 和 POST:
curl -sS https://api.github.com/zen curl -sS -X POST https://api.github.com/zenGET 应返回一句文本;POST 应被 OpenShell 拒绝,响应中包含
policy_denied。这样就能看到“允许连接”和“允许写入”是两层不同的控制。 -
在宿主机终端 C 中查看刚才的规则与拒绝记录:
openshell policy get api-demo --full openshell logs api-demo --since 5m --source sandbox日志应能定位发起程序、目标地址和被拒绝的请求方法。如果首个请求已经成功,先查看完整策略中是否已有允许规则,再比较更新前后的访问范围。
换成自己的项目
迁移时按这四处调整:
| 替换什么 | 根据什么决定 |
|---|---|
| 上传目录 | 选本次任务需要的项目;Git 仓库上传默认遵循 .gitignore |
| Agent 镜像 | 镜像中必须已有 Agent 和所需工具,使用明确的镜像引用 |
| Provider | 按模型服务配置凭据、端点和镜像内的实际程序路径 |
| 网络规则 | 按任务需要的服务和读取/写入范围开放 |
将下面方括号替换后发给沙箱内的 Agent:
项目位于 [沙箱工作目录下的项目路径]。
目标是 [本次希望完成的改动]。
可以修改 [文件范围],保留 [不需要改动的内容]。
需要查阅或调用的服务是 [域名及用途]。
先读取已有文件,说明实施步骤,再完成改动并给出检查结果与产物路径。
这是本站提供的需求模板。文件限制还需在创建沙箱时用策略落实;请求文字用于表达任务,不会自动成为 OpenShell 权限规则。自定义策略见策略文档。
取回所需产物后,在宿主机终端删除本次练习沙箱:
openshell sandbox delete api-demo
openshell sandbox delete my-agent
如果你还创建了概览用法里的 demo,也可用 openshell sandbox delete demo 删除。