Skip to main content

Cosmonic Agent SDK

The Cosmonic Agent SDK is a set of interfaces for building agents composed of sandboxes that are lightweight enough to run at massive density.

Each sandbox is deny-by-default: it starts with no files, network, config, environment variables, or secrets, and gets only the capabilities granted to it. You write the code that decides what to do next, and the platform runs it with exactly the capabilities specified.

Breaking down an agent​

An agent is several pieces working together: the loop that decides what to do, a model, the tools the loop can call, and a record of the conversation. The Agent SDK splits those separate concerns into separate parts:

  • The loop you write runs in its own sandbox with no network and no files. It reaches the model, its tools, and its conversation only by asking the host.
  • The host is an isolated sandboxed runtime that runs your code. It makes every model call over strongly typed interfaces, keeps the conversation, and decides which tools a session has.
  • Each tool is its own sandboxed component with its own narrow set of capabilities, such as one folder or one website.

The Agent SDK is organized into three parts:

  • The interfaces, published as the open cosmonic:agent typed interface package.
  • The hosts that run agents built on them: Cosmonic Desktop on your machine and Cosmonic Control on Kubernetes. Cosmo, our own agent and command-line host, is coming soon. The same agent runs on each without changes.
  • Agent harnesses: minimal-agent is a small reference harness in Rust. You can also use harnesses built from Codex, Pi, and others.

Open source, on your machines​

At heart, the Agent SDK is a set of open interfaces in the cosmonic:agent typed interface package. The hosts, the harnesses, and your tools are all built against it.

  • Open source. cosmonic:agent is licensed Apache 2.0. Its source is in the agent-sdk repository, and each release is published as a WIT package to ghcr.io/cosmonic-labs/cosmonic/agent (0.4.2 today), so a component can depend on it with wkg. The minimal-agent reference harness is Apache 2.0 too, and so is wasmCloud, the CNCF project the hosts are built on.
  • On your machines. There is no hosted sandbox service in the path. Agents, tools, and sessions run wherever you run the host: your laptop with Cosmonic Desktop, or your own Kubernetes clusters with Cosmonic Control, in your cloud or data center, air-gapped included. Model calls go from your host to the provider you choose, with your keys.
  • No lock-in. An agent is a standard WebAssembly component that imports open interfaces. Any host that serves them can run it, and the same agent image runs on Desktop and Control without changes. The model is a host setting, MCP servers run as sandboxed services alongside your tools, and sessions go to whatever store the host uses.

How the Agent SDK documentation is organized​

Start with the quickstart to build and run an agent. Read the concepts to understand the design, use the guides for specific tasks, and look up exact names and fields in the reference. To understand the design first, start with Anatomy of an agent.

Quickstart​

  • Quickstart: build the minimal-agent harness in Rust, run it on Desktop, change it, give it a tool, and see what it could reach and what it called.

Concepts​

  • Anatomy of an agent: the agent harness, the host, models and tools, and what happens during one run, including how an agent finds and adds tools as it works.
  • Sessions: why the host keeps every session, how sessions survive restarts and long conversations, where they live, what any store has to do, and how they are shared.
  • Capabilities: how every part of an agent starts with nothing and is granted only what it needs.
  • Tools: how an ordinary component becomes a tool a model can call, how big a tool should be, and how MCP servers run as sandboxed services.
  • Security model and limits: the trust boundaries, what the sandbox guarantees, and what it does not.

Guides​

Harnesses​

  • Harnesses: what an agent harness is, and the ones you can run or learn from.

Reference​

Last updated on by Eric Gregory