Quickstart

This walkthrough takes you from an empty directory to a running, inspectable agent capsule using nothing but a manifest. You declare what the capsule depends on and is allowed to do, install those dependencies, hand it a task, run it, and read back exactly what it did. Everything the capsule can reach is declared up front — nothing else is permitted.

The relevant manifest options are:

Option	Controls
artifacts[].runtime	Whether a declared artifact is a driver, tool, hook, or skill
inference.driver.artifact	Which driver artifact performs the model calls
inference.model	Which model the driver calls

---

Step 1 — declare the capsule in murmur.yaml

Create a murmur.yaml file. A minimal agent capsule declares its identity, one driver artifact, the API host it is allowed to reach, and how inference is configured:

AnthropicOpenAIDeepSeek

name: my-agent
version: "0.1.0"

artifacts:
  - name: murmur/driver-anthropic
    version: "0.19.0"
    runtime: driver
    gateway:
      endpoint: https://api.anthropic.com
      api_key: ${ANTHROPIC_API_KEY}

inference:
  transport: http
  model: claude-sonnet-5
  driver:
    artifact: murmur/driver-anthropic

name: my-agent
version: "0.1.0"

artifacts:
  - name: murmur/driver-openai
    version: "0.19.0"
    runtime: driver
    gateway:
      endpoint: https://api.openai.com/v1
      api_key: ${OPENAI_API_KEY}

inference:
  transport: http
  model: o3-mini-high
  driver:
    artifact: murmur/driver-openai

name: my-agent
version: "0.1.0"

artifacts:
  - name: murmur/driver-deepseek
    version: "0.17.0"
    runtime: driver
    gateway:
      endpoint: https://api.deepseek.com
      api_key: ${DEEPSEEK_API_KEY}

inference:
  transport: http
  model: deepseek-r1
  driver:
    artifact: murmur/driver-deepseek

The driver entry's gateway.api_key field reads from the environment at run time. Export your provider key in the shell you will run from:

export ANTHROPIC_API_KEY=sk-ant-...

This manifest is the entire contract. The capsule reaches its inference provider through the runtime, which holds the API key, and nothing else — no shell, no filesystem, no network destinations, because none are declared.

---

Step 2 — install the declared artifacts

mur install reads murmur.yaml, resolves every artifact declared in it, and fetches them in parallel into the project-local store. Run it once before the first run:

mur install

Different ways to install artifacts

mur install fetches an artifact from the source of its scope. murmur/ artifacts come from the built-in source, murmur-nexus/default-artifacts, with no configuration.

Option A — name the source of a scope in ~/.murmur/config.yaml:

registry:
  sources:
    - repo: <owner>/<repo>
      token: "${GITHUB_TOKEN}"

Then install by full name, with or without a version:

mur install <owner>/<artifact-name>@<version>

Option B — pass a full GitHub reference and skip configuration entirely:

mur install github:<owner>/<repo>@<tag>

See Installing artifacts to learn more.

mur run verifies that every declared artifact is installed before it starts. Skipping this step makes the next one exit immediately with error[E-RUN-008] and an install hint.

---

Step 3 — write the task

Create a task.md file describing what the agent should do. With this minimal manifest the capsule has inference only — no tools — so keep the first task to something the model can answer directly:

Explain what makes an infrastructure deployment reproducible, in three bullet points.

---

Step 4 — run the capsule

Pass the task file with --task. mur run stages the declared artifacts, hands the agent the task, starts the capsule's local HTTP server, and drives the agent loop to completion:

mur run --task task.md
murmur: url localhost:52222
session: ses_019ed2af53da75c2aefee84ee10c34af
status:  ok

The session: value identifies this run. The capsule worked in workdir/<session_id>/. The model's final text (out/result.txt), the structured trace (trace.jsonl) and runtime logs (logs/) are kept in the session's records directory, ~/.murmur/records/<this directory>/workdir/<session_id>/, where mur trace show reads them. Read the result directly with:

cat ~/.murmur/records$PWD/workdir/*/out/result.txt

---

Step 5 — inspect the run

Every session writes a structured trace.jsonl to its records directory. mur trace show reads the most recent one and prints a human-readable summary — turns, token usage, tool calls, and exit status:

mur trace show

Different ways to identify a session

mur trace show with no argument reads the most recent session:

mur trace show

To name another one, pass an ordinal counting back from the newest (@2), the last 4 or more characters of its ID (3e4b), the full ID, or a path to its trace.jsonl:

mur trace show @2
mur trace show 3e4b
mur trace show ses_6801f81dd28b4a9daf434e8324c4793e
mur trace show path/to/trace.jsonl

Use --workdir <path> if your session directories are not under ./workdir. Every command that names a session takes the same addresses — see Session addresses.

Other trace exploration commands

mur trace has four subcommands for exploring session output:

mur trace show — print the full trace for a session to the terminal.

mur trace steps — show a turn-by-turn summary of what the agent did in a session. Pass --verbose to include a truncated summary of each tool's input.

mur trace diff — compare the traces of two sessions side by side, or with no arguments the two most recent. Useful for spotting behavioural regressions between runs.

mur trace report — generate a structured summary report from a session's trace. Covers token usage, tool calls, latency, and other session-level metrics.

The trace is written by the runtime, not the capsule, so it exists after every session and cannot be suppressed or falsified by the agent. It is the authoritative record of what the run actually did.

---

Summary

Step	Command	What it does
Declare	edit murmur.yaml	Pins the driver artifact, the allowed host, and the model — the capsule's whole contract
Install	mur install	Fetches every artifact declared in murmur.yaml into the project-local store
Run	mur run --task task.md	Stages the artifacts, feeds in task.md, and drives the agent loop to completion
Inspect	mur trace show	Prints the runtime-written trace for the most recent session

Pin every artifact to an exact version and the manifest becomes an execution contract you can audit, roll forward, and roll back. From here, grant more capabilities: lock down its capabilities, shape its behavior with a system prompt, or connect two capsules.

---

Want to use a subscription?

A capsule can drive inference through a harness CLI you are already logged into, spending that login instead of an API key. Set inference.transport: process, declare a process driver artifact — the component that knows how to drive that one CLI — and declare the variables it needs in capabilities.env.allow. There is no capabilities.network and no api_key: the harness reaches its provider with its own credentials.

This is a secondary path; transport: http remains the primary, fuller-featured way to run a capsule. Before choosing it, read Run a capsule on your subscription, which states what this transport costs you.

Create a manifest

Create a murmur.yaml in an empty directory. murmur/driver-claude-code drives the Claude CLI:

name: my-capsule
version: "1.0.0"
artifacts:
  - name: murmur/driver-claude-code
    version: "0.9.0"
    runtime: driver
capabilities:
  env:
    allow: [HOME, PATH]   # every variable the driver's describe() requires
inference:
  transport: process
  driver:
    artifact: murmur/driver-claude-code
  max_turns: 10

Install the driver before the first run:

mur install

Run the capsule

In the same directory, run the capsule with a task passed inline:

mur run --task "When I say Ping you say?"

Inspect the capsule's output at out/result.txt in the session's records directory, for example:

> cat ~/.murmur/records$PWD/workdir/*/out/result.txt
Pong! 🏓

Calling tools

Tool artifacts work under transport: process too — declare them exactly as you would for transport: http, and mur trace show records each tool call. Murmur stands up a loopback tool server, the driver points the harness at it, and the harness's own built-in tools are stripped, so the model is offered the capsule's tools and nothing else. max_turns counts one turn per model step here just as it does on transport: http — roughly one per tool call plus a final turn — so budget it the same way (a too-low limit fails with error[E-RUN-033] naming the kind max-turns).

Observability differs from transport: http

Because the harness owns the model calls, the per-turn token counts mur trace show prints are the harness's own report of what it spent, relayed by the driver, rather than requests Murmur measured. A driver that reports no counts leaves them out of the trace entirely. Turns, tool calls, declared tools, exit status, system prompts and lifecycle hooks work the same on both transports.

Learn more about the murmur.yaml manifest in the Manifest Schema reference.