OpenShell：NVIDIA 的 AI 智能體沙盒執行環境現已提供中文版 README

OpenShell's install command is one line, but the README that follows it is not. NVIDIA's project ships a fair amount of documentation: policy semantics, a formal verification step, a gateway/supervisor/sandbox architecture, and a support matrix that rules out a good chunk of machines people will try it on. For a Chinese-speaking developer evaluating whether to spend an afternoon on it, that's a real cost before the first openshell sandbox create ever runs.

A translated version of the repository now exists at yangshun2005/OpenShell-cn. It is a documentation translation, not a fork of the code. The original is NVIDIA/OpenShell, 19,704 stars, written in Rust, Apache-2.0.

Below is what the project actually does, what the Chinese version adds, and the parts of the setup that tend to go wrong.

What OpenShell is for

The one-line description NVIDIA uses is "the safe, private runtime for autonomous AI agents." The longer version: agents are most useful when they can read files, install packages, call APIs, and use credentials. Those are also the four things you least want an unsupervised process doing on your machine.

OpenShell's answer is not to remove the capabilities but to declare them. You write a policy describing what each agent may touch, and the runtime enforces it. Two mechanisms do the work:

• Kernel-level enforcement. Each agent runs in an isolated sandbox. The kernel is instrumented so that every file access, every syscall, and every outbound network connection is checked against policy. Credentials never reach the agent directly — OpenShell injects them into requests headed to approved endpoints only.
• Formal verification of policy changes. Before a policy change takes effect, OpenShell checks what new access it would grant. If a change would let an agent use a credential against a new host, or call a new API method, it gets flagged and waits for human review.

That second point is the interesting design choice. Most sandboxing tools treat policy as configuration you edit and reload. OpenShell treats a policy diff as something to be analyzed, which is a different threat model — it assumes the person editing the policy might be an agent, or might be acting on an agent's suggestion.

Getting it running

The quick start is two commands, and the first one needs a working container or virtualization backend already in place:

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
openshell sandbox create --name demo

The installer sets up both the CLI and a local gateway.

Platform requirements

This is where people lose time, so it's worth listing plainly:

• OS: Linux, macOS on Apple Silicon, or Windows with WSL 2 (experimental).
• Runtime dependency: Docker, Podman, or host virtualization — one of the three, already installed.
• Linux: the install script pulls a Debian or RPM package. The script states a minimum glibc of 2.28.
• macOS: Apple Silicon only. Installed via a Homebrew formula, which manages the binary layout and the launchd service lifecycle.
• Python SDK: Python >= 3.11 (per pyproject.toml).
• Building from source: the workspace declares rust-version = "1.94" and edition = "2024" in Cargo.toml.

Windows support being labeled experimental is not boilerplate. If you're on an Intel Mac, you're out — there's no path in the support matrix for you.

The default sandbox has no agent in it

openshell sandbox create --name demo gives you a minimal Ubuntu image. No agent is installed. This surprises people who expect the demo to do something agent-like out of the box.

To run an actual agent, the official docs point at Run Your First Agent, which wires OpenCode to a free OpenRouter model and walks through the approval flow when the agent requests new access. That approval flow is the part worth reading carefully — it's the human-in-the-loop side of the formal verification described above.

There's also an optional step for coding agents that support skills:

npx skills add NVIDIA/OpenShell

Telemetry is on by default

Worth stating up front rather than burying. OpenShell collects anonymous telemetry. Per the documentation, it's limited to operational categories and counts — no sandbox names, hostnames, file paths, prompts, or credentials.

To turn it off:

# on the gateway
OPENSHELL_TELEMETRY_ENABLED=false

For Helm installs, set server.telemetryEnabled=false instead.

The docs also recommend keeping the SDK and gateway on the same OpenShell version. Version skew between the two is the kind of thing that produces confusing failures rather than clean errors.

What the Chinese version actually contains

The repository at yangshun2005/OpenShell-cn is structured in two layers, and the split matters.

Layer one: a Chinese quick-start guide written for this translation. This is explicitly marked as supplementary material, not part of the original README. It covers:

• What the project is and what problem it solves, in a few paragraphs
• The shortest path to a running sandbox
• The full environment requirements list, including the glibc, Rust, and Python version floors
• A "common pitfalls" section

That pitfalls section is the most useful part, because it collects the failure modes that are scattered across the upstream docs: the empty default sandbox, the Apple Silicon restriction, the mandatory container backend, telemetry defaults, and SDK/gateway version alignment.

Layer two: a translation of the upstream README itself. The stated goal is fidelity to the original. The translation date is recorded as 2026-10-25, and the original English README is kept alongside as README_en.md so you can diff them.

The repository explicitly invites issues and PRs for inaccurate translations. Given that OpenShell is at 0.1.x with a stated cadence of stable releases, the English docs will move; a translation will always lag somewhat. My sample of one reading suggests the quick-start layer is the more durable part, since it describes requirements and pitfalls rather than API surface.

Where the translation helps, concretely

Three places, I think.

Version floors. "glibc 2.28", "rust-version = "1.94"", "Python >= 3.11" — these are easy to skim past in a long English README and expensive to discover after a failed build. Having them collected in one place in your first language reduces the chance you start an install that can't succeed.

The gap between "installed" and "working." The upstream quick start is honest that the default sandbox is bare, but that fact sits in a paragraph after the commands. The Chinese guide puts it in the pitfalls list, which is where people look when the demo doesn't behave as expected.

Policy semantics. This is the part I'd want translated most carefully, because policy is where the project's whole value proposition lives. Getting the enforcement model wrong — assuming policy is advisory, or that credentials are visible to the agent — leads to a very different mental model of what you've deployed. The translated README covers the enforcement and verification mechanisms directly.

What it doesn't do

It doesn't change the software. If you're building against OpenShell, you're building against NVIDIA's code, and the translated repo is a reading aid. Bug reports and feature requests belong upstream.

It also doesn't solve the network problem. The install script downloads release artifacts from GitHub, and the translation notes that users in mainland China may need a proxy or an accelerated download path. The original documentation doesn't provide a mirror, and neither does the translation — it just flags the issue so you're not debugging a timeout wondering whether the script is broken.

Should you read it

If you already read English technical documentation comfortably, the upstream README is fine and always current. The Chinese version earns its place for two groups: developers who'd rather absorb the requirements and pitfalls in Chinese before committing an afternoon, and teams where the person evaluating the runtime isn't the person who'll operate it — handing over a translated quick-start is cheaper than a meeting.

The project is Apache-2.0, so the licensing question is settled either way. Start with the quick-start layer, then read the translated README for the policy model, then go upstream for anything version-specific.

Chinese documentation: https://github.com/yangshun2005/OpenShell-cn

I'm an independent enterprise AI delivery consultant — private LLM deployment, RAG, agent workflows, AIOps. If your team is stuck somewhere in that stack, my inbox is open.