First classify AI work as either "understanding this machine" or "completing a job," then choose the smallest, clearest security boundary.
This Skill does not replace the native sandbox of Codex, Claude Code, or other harnesses, nor does it force all work into OpenShell. The goal is to avoid two kinds of mistakes:
- For the sake of isolation, cramming debugging work that needs real host state into a container, and patching the holes with a large number of bind mounts.
- For the sake of convenience, putting long-running autonomous, cross-API, credential-bearing workers directly on the real host.
Core model
AI task
|
+------------+------------+
| |
工作物件是「這台機器」？ 工作物件是「一份任務」？
| |
yes yes
| |
v v
Codex / Claude Code / OpenShell
當前 harness 原生沙盒 isolated worker
| |
host-native filesystem cloned/copied workspace
host runtime / logs scoped network/API
host process state brokered credentials
| |
+------------+------------+
|
若同時需要兩者
|
v
split into phases
Routing principles
First ask:
Is the primary work object of this AI "the real state of this host right now," or "a task that can be independently encapsulated and discarded once completed"?
Route A: harness native sandbox
Choose Codex, Claude Code, or the current harness's native sandbox when conditions include:
- Needing to directly read the host's
/etc、/var/log、/proc、/sys, package state, systemd, socket, or process state. - Needing to understand both the repo and the actual deployment environment.
- The user is interactively debugging and will supervise operations in real time.
- The primary value of the work comes from "seeing the real host," not from creating a clean worker.
- You can use the native sandbox for "broad read-only plus a small number of explicitly writable paths."
Do not equate "native sandbox" with a specific technology. Use the mechanism that the current harness actually provides on the current OS:
- Codex: use the Codex native sandbox.
- Claude Code: use the Claude Code native sandbox.
- Other harnesses: use only when their native sandbox capability can be verified; do not assume it exists merely because a name or documentation claims it.
Typical shape:
Host
|
+-- real /etc
+-- real /var/log
+-- real runtime/process state
+-- real repo
|
v
Codex / Claude Code / harness
|
v
native sandbox
|
+-- host-wide read as needed
+-- explicit writable workspace
+-- dangerous mutation denied or approval-gated
Route B：OpenShell isolated worker
Choose OpenShell when conditions include:
- The work can be reconstructed from a repo, artifact, task description, or explicit input.
- The AI will run autonomously for a long time, with no one continuously watching.
- Needing to span multiple external systems such as Git hosting, cloud APIs, CI, issue trackers, artifact registries, and internal APIs.
- Credentials are needed, but the agent process should not directly hold real credentials.
- Needing explicit control over egress, API method/path, provider, and credential destination.
- Needing to run multiple workers simultaneously, with filesystem and lifecycle isolation from each other.
- Wanting to directly destroy the worker upon completion, leaving no host runtime pollution.
Typical shape:
Task / Issue / Queue
|
v
Orchestrator
|
v
OpenShell
|
+----+----+
| |
Codex Claude Code
| |
+----+----+
|
isolated workspace
|
+------+------+------+
| | |
Git hosting Cloud Internal API
policy policy policy
In the OpenShell path, OpenShell is the primary external capability boundary. Do not rely on a given harness's built-in approval to represent the overall security boundary.
Route C: hybrid tasks
If a task simultaneously requires:
- Real host state;
- isolated worker；
- External APIs / credentials;
- Long-running autonomous execution;
Do not directly bind mount the entire host into OpenShell.
Prefer splitting into:
Phase 1: host-aware investigation
|
v
harness native sandbox
|
+-- read logs
+-- inspect config
+-- inspect runtime/process
+-- extract minimal evidence
|
v
bounded evidence / artifact
|
Phase 2: task execution
|
v
OpenShell worker
|
+-- clone/copy repo
+-- modify
+-- test
+-- call approved APIs
+-- create patch/branch/PR
Only consider an OpenShell explicit read-only bind mount when Phase 2 must continuously read live host data and cannot be replaced by a snapshot, log export, API, or explicit artifact.
OpenShell Prerequisite Gate
Whenever the routing result requires OpenShell, before executing any OpenShell setup, policy, provider, or sandbox command:
- First confirm that the current harness can read NVIDIA OpenShell skills.
- If installation cannot be proven, run:
npx skills add NVIDIA/OpenShell
- After installation, first read the NVIDIA/OpenShell skill relevant to this task, then generate or modify the OpenShell policy.
- Do not treat NVIDIA/OpenShell skills as content bundled with this Skill; this is an independently installed upstream dependency.
- If the upstream skill cannot be installed or read, do not guess the latest OpenShell policy schema or CLI parameters from memory; stop at the design/planning layer, or switch to a path that does not depend on OpenShell.
Harness Native Sandbox Gate
Before taking Route A:
- Confirm the current harness and OS.
- Confirm that the harness's native sandbox is actually enabled right now.
- Confirm that at least the following can be expressed:
- the required read scope;
- writable workspace；
- network boundary；
- the necessary approval / escalation.
- If the native sandbox does not exist, is disabled, or cannot satisfy the minimum boundary, do not pretend it is safe; switch to OpenShell, Docker/VM isolation, or stop high-risk mutation.
Do not write bubblewrap as a cross-platform premise. The native mechanisms of Linux, macOS, and Windows differ; routing is determined only by whether the harness can provide the required boundary on the current platform.
Decision Matrix
| Task Characteristic | Harness Native Sandbox | OpenShell |
|---|---|---|
Read real host /etc / logs / process |
Preferred | Not preferred |
| Interactive system debug | Preferred | Not preferred |
| Single repo, user supervising nearby | Preferred | Optional |
| isolated disposable coding worker | Available | Preferred |
| Long-running autonomous task | Not preferred | Preferred |
| Multiple workers in parallel | Limited | Preferred |
| Multiple external system APIs | Possible but scattered | Preferred |
| Credentials must not be exposed to the agent | harness-specific | Preferred |
| Fine-grained API method/path restrictions | harness-specific | Preferred |
| Need to directly understand the host runtime | Preferred | Unless explicitly RO bind |
| Entire environment can be discarded after completion | Ordinary | Preferred |
Quick decision
Decide in order:
-
Is live host state needed?
- Yes → Route A.
- No → next question.
-
Can the work be reconstructed from explicit inputs?
- No → Route A, or do Route A first for evidence collection.
- Yes → next question.
-
Is it long-running autonomous, across multiple external systems, requiring credentials, or multiple workers?
- Yes → Route B.
- No → native sandbox is usually simpler.
-
Do both conditions hold?
- Split Route C; do not do a broad host bind first.
Typical cases
System failure analysis
「分析目前這台 server 的 Nginx / runtime / logs，找出 timeout 根因」
Route:
native-sandbox
Reason: the real host is the work object.
Interactive code change
「修改目前 repo，跑測試，我在旁邊看結果」
Route:
native-sandbox
Reason: single workspace, interactive supervision, native sandbox has the lowest cost.
Issue to PR
「收到 issue 後自動 clone、修改、測試、push branch、開 PR」
Route:
openshell
Reason: task-isolated, reproducible, requires a Git provider and long-running autonomous execution.
Fix after cross-system investigation
「先看 staging host 的實際 logs 與 config，再修 repo 並呼叫 Git / cloud API」
Route:
native-sandbox -> evidence -> openshell
Reason: the investigation phase needs a host-native view; the implementation phase suits an isolated capability boundary.
OpenShell Usage Principles
After routing to OpenShell:
- The workspace is created independently by default, and the host filesystem is not exposed by default.
- Providers / credentials use OpenShell's mechanisms; do not put long-term secrets directly into the agent environment.
- Egress and API scope open only the minimal set needed for this task.
- Host bind mount is not used by default; if necessary, prefer read-only, and explicitly list the source, target, reason, and removal conditions.
- Do not put production mutation permissions and general coding permissions in the same worker.
- After the worker finishes, keep the necessary artifacts / commits / logs, then stop or delete the sandbox.
Do not do this
Do not unify for the sake of unification
所有 Codex / Claude Code
|
v
OpenShell
|
v
大量 host bind mounts
This would lose both the simplicity of host-native debug and the clean boundary of an isolated worker.
Do not treat native approval as the complete boundary of an autonomous worker
Approval in Codex, Claude Code, or other harnesses is great for interactive work, but a cross-system autonomous worker should still have an independent network, credential, and API capability boundary.
Do not use OpenShell to simulate an entire real host
If the core of the work is understanding an existing machine, prefer the harness's native sandbox. OpenShell's explicit bind mount is the exception, not the default architecture.
Route output
When an explicit record is needed, output one line:
execution_boundary=native-sandbox reason=host-aware
Or:
execution_boundary=openshell reason=autonomous-cross-system
Or:
execution_boundary=split reason=host-investigation-plus-isolated-execution
If OpenShell is chosen, add:
openshell_skill=verified
It can only be marked when it has been confirmed that the NVIDIA/OpenShell skill can be read verified。