Skip to main content

NVIDIA OpenShell Sandbox

Cosmonic Desktop is a local AI sandbox for NVIDIA OpenShell: the code OpenShell writes is compiled to WebAssembly and runs on your own machine with no access to your files, network, or keys until you grant it. Two settings wire it up, one for launching OpenShell from Builder with the sandbox playbook and one for installing Desktop's MCP server into OpenShell; use either or both.

Sandbox NVIDIA OpenShell with Cosmonic Desktop​

1. Settings → Agents: launch OpenShell from Builder​

Open Settings → Agents. The Detected agents card lists every coding agent Desktop found by its home directory (~/.openshell) or on your login shell's PATH, and says whether each one is launchable from Builder. In the Skills card, turn on NVIDIA OpenShell to install the sandbox policy template at ~/.openshell/cosmonic/. This is the same install the one-time Set up your coding agents dialog offers on first run; nothing is installed silently.

The policy registers Desktop's MCP server inside each OpenShell sandbox at creation time. Once it is installed, Builder can launch OpenShell directly: open Builder, pick OpenShell as the agent, describe what you want, and its output lands in a sandboxed workload you can inspect before it runs.

2. Settings → MCP Server: install Desktop's MCP server into OpenShell​

Open Settings → MCP Server for the server's status and the manual snippet. OpenShell registers MCP servers per sandbox, through a policy applied at sandbox-create time, so there is no persistent client config for Desktop to edit and OpenShell is not in the Install in your AI client list. Instead, Settings → Agents installs a sandbox policy template rendered with this machine's daemon paths, and Builder applies it automatically (via OPENSHELL_SANDBOX_POLICY) when it launches OpenShell.

To apply the policy by hand when creating a sandbox:

openshell sandbox create --policy ~/.openshell/cosmonic/policies/cosmonic-desktop-mcp.yaml <name>

3. Verify the connection​

Inside a sandbox created with the policy, the cosmonic_* tools are available to the agent. Review the bundled README under ~/.openshell/cosmonic/ before applying the policy.

Skills over MCP​

Desktop's MCP server also publishes its skill family—cosmonic-sandbox, cosmonic-go, cosmonic-nats, cosmonic-nats-tuning, and cosmonic-kafka—through the MCP Skills extension (io.modelcontextprotocol/skills). A client that supports Skills over MCP gets the playbooks the moment it connects, with nothing written to its skills directory, so the MCP registration above is enough on its own for those clients. The on-disk skill from Settings → Agents covers clients that read a skills directory but do not yet speak the extension, and it is what Builder relies on to launch OpenShell.

What OpenShell can do once connected​

Its full tool surface (observe, deploy, build) and the guardrails are covered in Connect Coding Agents; the tools work only while Cosmonic Desktop is running.

Frequently asked questions​

How do I sandbox NVIDIA OpenShell?

Install Cosmonic Desktop, then under Settings → Agents turn on NVIDIA OpenShell to install the cosmonic-sandbox policy, and under Settings → MCP Server register Desktop’s MCP server in OpenShell. From then on the code OpenShell writes is compiled to WebAssembly and runs in a local sandbox with no access to your files, network, or keys until you grant it.

Does OpenShell itself run inside the sandbox?

No. OpenShell keeps running in your terminal or IDE exactly as before. What changes is where its output executes: the programs and MCP servers it builds run as sandboxed WebAssembly workloads on your machine instead of directly on your host.

Do I need both the skill and the MCP server?

They do different jobs. The MCP server gives OpenShell the tools to build, deploy, and observe sandboxed workloads; the skill gives it the know-how to use them by default. Desktop also publishes its skills over the MCP Skills extension, so a client that supports Skills over MCP gets the playbook from the connection alone.

What can the code OpenShell writes reach inside the sandbox?

Nothing by default. Each workload starts with no filesystem, network, or credential access; you grant exactly the capabilities it needs in its manifest, and everything else stays denied. The same manifest deploys unchanged to Cosmonic Control on Kubernetes.

Why does OpenShell get a policy instead of a skill?

OpenShell has no user-level skills directory or MCP config: every sandbox is configured from a policy at creation time. Desktop therefore installs a policy template that registers its MCP server inside each sandbox, and the skills still reach the agent over MCP through the Skills extension.

Next steps​

Last updated on by Liam Randall