---
title: "Quickstart"
description: "This walkthrough takes you from an empty directory to a running, inspectable agent capsule using nothing but a manifest."
canonical_url: "https://docs.murmur.nexus/getting-started/quickstart"
last_updated: "2026-09-12T21:31:57.000Z"
---

# Quickstart

This walkthrough takes you from an empty directory to a running, inspectable agent [capsule](/concepts/capsules.md) 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](/reference/manifest.md#field-artifacts) | Whether a declared artifact is a driver, tool, hook, or skill |
| [inference.driver.artifact](/reference/manifest.md#field-inference) | Which driver artifact performs the model calls |
| [inference.model](/reference/manifest.md#field-inference) | 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:

**Anthropic**

```yaml
name: my-agent
version: "0.1.0"

artifacts:
  - name: murmur-driver-anthropic
    version: "1.0.0"
    runtime: driver

inference:
  transport: http
  endpoint: https://api.anthropic.com
  model: claude-sonnet-5
  api_key: ${ANTHROPIC_API_KEY}
  driver:
    artifact: murmur-driver-anthropic
```

**OpenAI**

```yaml
name: my-agent
version: "0.1.0"

artifacts:
  - name: murmur-driver-openai
    version: "1.0.0"
    runtime: driver

inference:
  transport: http
  endpoint: https://api.openai.com
  model: o3-mini-high
  api_key: ${OPENAI_API_KEY}
  driver:
    artifact: murmur-driver-openai
```

**DeepSeek**

```yaml
name: my-agent
version: "0.1.0"

artifacts:
  - name: murmur-driver-deepseek
    version: "1.0.0"
    runtime: driver

inference:
  transport: http
  endpoint: https://api.deepseek.com
  model: deepseek-r1
  api_key: ${DEEPSEEK_API_KEY}
  driver:
    artifact: murmur-driver-deepseek
```

The `api_key` field reads from the environment at run time. Export your provider key in the shell you will run from:

```bash
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:

```bash
mur install
```

> **Different ways to install artifacts**
>
> `mur install` needs to know where to fetch artifacts from. You have two options:
>
> **Option A — configure a registry source** in `~/.murmur/config.yaml`:
>
> ```yaml
> registry:
>   default: official
>   sources:
>     - name: official
>       type: github
>       repo: <owner>/<repo>
>       token: "${GITHUB_TOKEN}"
> ```
>
> Then install by artifact name and version:
>
> ```bash
> mur install <artifact-name@version>
> ```
>
> **Option B — pass a full GitHub reference** and skip configuration entirely:
>
> ```bash
> mur install github:<username>/<repo>@<tag>
> ```
>
> See [Installing artifacts](/reference/installing-artifacts.md) 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:

```text
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, copies `task.md` into the capsule's working directory, starts the capsule's local HTTP server, and drives the agent loop to completion:

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

The `session:` value identifies this run. Everything the run produces lands under `workdir/<session_id>/`: the task input (`task.md`), the model's final text (`out/result.txt`), the structured trace (`trace.jsonl`), and runtime logs (`logs/`). The session workdir is the single place to look — read the result directly with:

```bash
cat workdir/*/out/result.txt
```

---

## Step 5 — inspect the run

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

```bash
mur trace show
```

> **Different ways to identify a session**
>
> `mur trace show` with no argument reads the most recent session:
>
> ```bash
> 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`:
>
> ```bash
> 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](/reference/cli.md#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](/how-to/lock-down-capsule.md), [shape its behavior with a system prompt](/how-to/capsule-system-prompt.md), or [connect two capsules](/how-to/capsules-a2a-messaging.md).

---

## Want to use a subscription?

Instead of a driver artifact and an API key, a capsule can drive inference through a provider CLI you are already logged into — the Claude CLI (Anthropic) or the Codex CLI (OpenAI). Set `inference.transport: process` and point `command` at the CLI — no driver artifact, no `capabilities.network`, and no API key.

This is a secondary path for spending a subscription rather than an API key; [`transport: http`](#step-1-declare-the-capsule-in-murmuryaml) remains the primary, fuller-featured way to run a capsule.

### Create a manifest

Create a `murmur.yaml` in an empty directory, using the CLI for the subscription you are logged into:

**Anthropic**

```yaml
name: my-capsule
version: "1.0.0"
inference:
  transport: process
  command: claude
  model: claude-opus-4-8   # optional — omit to use your subscription's default
  max_turns: 10
```

**OpenAI**

```yaml
name: my-capsule
version: "1.0.0"
inference:
  transport: process
  command: codex
  model: gpt-5.5   # optional — omit to use your subscription's default
  max_turns: 10
```

### Run the capsule

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

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

Inspect the capsule's output at `workdir/<session_id>/out/result.txt`, for example:

```bash
> cat 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. `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-007]: max_turns exceeded`).

> **Observability differs from `transport: http`**
>
> Because the CLI owns the model calls, `mur trace show` records turns, tool calls, declared tools, and exit status — but **not** per-turn token usage. When you need full token accounting, use `transport: http`. System prompts and lifecycle hooks apply on both paths.

Learn more about the `murmur.yaml` manifest in the [Manifest Schema reference](/reference/manifest.md).