Skip to main content

Connect Coding Agents

Cosmonic Desktop ships a Model Context Protocol (MCP) server, so Claude Code, OpenAI Codex, Gemini CLI, or any MCP client can drive it—taking a prompt like "build me an API" all the way to a running, sandboxed workload. (Desktop also works in the other direction, running MCP servers as sandboxed workloads—see Sandbox MCP Servers.)

This page is the reference for the connection itself—the server, the clients, the tools. For a step-by-step run through the whole loop, follow Sandboxing AI, walkthrough 2 of the quickstart.

Diagram of the two MCP directions. A "Coding agent" box (Claude Code, Gemini CLI, any MCP client) sends arrow 1, labeled "drives Desktop", to the cosmonicd MCP server inside a Cosmonic Desktop box — with cosmonic_* tools for inspect, deploy, logs, and status. Arrow 2, labeled "calls sandboxed tools", goes to "your MCP server", drawn with a dashed border as a Wasm workload that is sandboxed with egress denied by default. This page covers direction 1.

The server​

The daemon's MCP server is on by default—there's nothing to install. It runs as cosmonicd mcp serve, a stdio process your MCP client spawns, which connects back to the running daemon over its Unix socket (named pipe on Windows). There's no network listener and no API token; the peer-checked socket is the boundary, and only your user's processes can reach it. The toggle in Settings → MCP Server controls whether Desktop advertises and auto-registers the server; a client you registered yourself keeps working until you remove that registration (for example, claude mcp remove cosmonic).

Connect a client​

The command every client needs is cosmonicd mcp serve, using the full path to the daemon binary (where it lives on each platform). The Settings → MCP Server screen has an Install in your AI client section that detects installed agents and registers the server for you; each agent also has a dedicated page with its manual registration and quirks:

Any other MCP client (Cursor, Zed, a custom host): it's plain stdio JSON-RPC—point the client at the same command.

Agent skills​

Connecting a client gives the agent the tools (the cosmonic_* MCP tools below). The cosmonic-sandbox agent skill gives it the know-how—it teaches the agent to deploy generated code to your local sandbox instead of running it raw on your host. The two are independent: the skill is a set of instructions dropped into the agent's own skills directory, not part of the MCP connection. It ships inside Desktop, so there's nothing to download.

How agents are detected. Desktop recognizes the coding agents already on your machine by their home configuration directory—~/.claude, ~/.codex, ~/.gemini, ~/.gemini/antigravity-cli (Google Antigravity, which shares the ~/.gemini home with Gemini CLI), ~/.openclaw, ~/.hermes, ~/.openshell. An agent counts as detected when that directory exists (or when the skill is already installed for it).

What happens by default. Nothing is installed silently. The first time Desktop runs with at least one agent detected, it shows a one-time Set up your coding agents dialog that lists every detected agent—each one pre-selected—and installs the skill into the agents you confirm. The dialog appears only once; afterward, install, update, or remove the skill for any agent at any time under Settings → Agent skills, which shows the bundled skill version and flags any agent whose installed copy is behind.

Where the skill is installed. Desktop copies the skill into each agent's own user-scope skills directory under your home folder. This is plain filesystem work with no daemon involved, and the layout is identical on macOS, Linux, and Windows:

AgentInstalled at
Claude Code~/.claude/skills/cosmonic-sandbox/
OpenAI Codex~/.agents/skills/cosmonic-sandbox/shared AgentSkills directory
Gemini CLI~/.gemini/skills/cosmonic-sandbox/
Google Antigravity~/.gemini/skills/cosmonic-sandbox/shared with Gemini CLI
OpenClaw~/.openclaw/skills/cosmonic-sandbox/
Hermes Agent~/.hermes/skills/cosmonic-sandbox/
NVIDIA OpenShell~/.openshell/cosmonic/policy template, not a skill

Each agent reads its skills directory natively, so the skill takes effect the next time you start the agent. A few agents depart from the plain pattern: OpenAI Codex installs into the shared ~/.agents/skills location (the cross-agent AgentSkills convention) rather than a Codex-specific path, Google Antigravity reads the same ~/.gemini/skills directory as Gemini CLI (installing for one covers both), and NVIDIA OpenShell receives a sandbox policy template rather than a SKILL.md—check its bundled README to validate and apply it. Removing the skill only ever deletes a package Desktop recognizes as its own, never an unrelated directory.

For Claude Code, this skill is the sandbox instructions on their own; the full Cosmonic plugin—slash commands, MCP wiring, and the sandbox gate—installs separately with claude plugin install cosmonic@cosmonic.

What the agent can do​

The server exposes thirteen cosmonic_* tools. They only drive the daemon (the agent writes code with its own file tools), and they group into three jobs:

  • Observe: cosmonic_host_status (daemon health and the ingress base URL, so no port guessing), cosmonic_list_workloads, cosmonic_logs, cosmonic_inspect (a component's WIT world—its declared imports and exports).
  • Deploy: cosmonic_synthesize (draft a Workload from an OCI ref or repo URL), cosmonic_apply_workload, cosmonic_workload (start/stop/delete), cosmonic_set_secret—which registers a secret reference (keychain, 1Password, AWS, env); the agent never handles the value.
  • Build: cosmonic_list_templates, cosmonic_scaffold_project, cosmonic_dev (build + run + watch), cosmonic_dev_logs, cosmonic_promote (build, push, and return a digest-pinned Workload draft). These share their project routes with Builder, so they work out of the box.

It also serves MCP resources: cosmonic://host, cosmonic://workloads, cosmonic://templates, cosmonic://catalog, and cosmonic://schema/workload. One of these, cosmonic://catalog, backs the Catalog feature and returns a feature_disabled error until it's enabled under Settings → Labs. There's also one prompt, build-and-deploy-api, which orchestrates the whole loop:

  1. The agent scaffolds a project from a starter template (rust-http, go-http, ts-http) and writes the handler code itself.
  2. cosmonic_dev builds, runs, and watches; cosmonic_dev_logs feeds compile and runtime errors back for the agent to fix.
  3. cosmonic_promote builds and pushes the component, returning a digest-pinned image reference in a ready-to-apply Workload.
  4. cosmonic_apply_workload schedules it—and the workload appears in your Workloads view, running in a sandbox, like any other.

The guardrails hold no matter who's driving: destructive operations require an explicit confirm, secrets stay references, images stay digest-pinned and signature-checked, and whatever the agent deploys runs under the same deny-by-default sandbox as anything you deploy by hand. And because the result is a standard Workload spec, the agent's output is one kubectl apply away from a Cosmonic Control cluster.

Next steps​

Last updated on by Liam Randall