Skip to main content

Claude Desktop Sandbox

Cosmonic Desktop is a local AI sandbox for Claude Desktop: the code Claude writes is compiled to WebAssembly and runs on your own machine with no access to your files, network, or keys until you grant it. Claude Desktop is an MCP host rather than a coding agent, so there is one setting to wire up: Desktop's MCP server from Settings → MCP Server. Claude Desktop then gets the tools, and the sandbox skills reach it over MCP.

Sandbox Claude Desktop with Cosmonic Desktop​

1. Settings → Agents: Claude Desktop is detected, nothing to install​

Open Settings → Agents. Claude Desktop appears in Detected agents when its app config directory exists, marked MCP-only: it is not launchable from Builder and there is no skill to install, because Claude Desktop has no skills directory. The playbooks reach it over MCP instead (see Skills over MCP below).

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

Open Settings → MCP Server. Under Install in your AI client, turn on Claude Desktop: Claude Desktop has no MCP CLI and its config sits outside the home dot-dir convention, so Desktop's toggle edits claude_desktop_config.json directly (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows, ~/.config/Claude/ on Linux). Restart Claude Desktop afterwards. This registers cosmonicd mcp serve as an MCP server in Claude Desktop's own configuration, and the cosmonic_* tools (observe, deploy, build) are available the next time you start it. Expand Instructions on the same card to copy the manual snippet instead.

To do it by hand, add the server to claude_desktop_config.json and restart Claude Desktop:

{
  "mcpServers": {
    "cosmonic": {
      "command": "/Applications/Cosmonic Desktop.app/Contents/Resources/cosmonicd",
      "args": ["mcp", "serve"]
    }
  }
}

3. Verify the connection​

After restarting, the cosmonic server shows in Claude Desktop's tools menu; ask Claude to list Cosmonic workloads and the cosmonic_* tools should answer while Desktop is running. Claude Desktop speaks stdio only, so sandboxed MCP-server workloads you publish from Desktop register through the bundled cosmonic-stdio shim; see Sandbox MCP Servers.

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 for the agents it launches.

What Claude Desktop 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 Claude Desktop?

Install Cosmonic Desktop, then under Settings → Agents turn on Claude Desktop to install the cosmonic-sandbox skill, and under Settings → MCP Server register Desktop’s MCP server in Claude Desktop. From then on the code Claude Desktop 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 Claude Desktop itself run inside the sandbox?

No. Claude Desktop 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 Claude Desktop 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 Claude Desktop 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.

Can Claude Desktop use the MCP servers I sandbox in Cosmonic Desktop?

Yes. Claude Desktop only speaks stdio, so an MCP-server workload running in a Cosmonic sandbox is registered through the bundled cosmonic-stdio shim pointed at that workload. The Sandbox MCP Servers guide covers it.

Next steps​

Last updated on by Liam Randall