> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paddock.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> Templates, agents, sessions, turns, events, and harnesses, and how they relate.

paddock has three layers: a **template** defines a kind of agent, an **agent** is one running instance of a template with its own sandbox, and a **session** is one endless conversation inside an agent.

```mermaid theme={null}
flowchart LR
  tpl["Template<br/>name@version"] --> a1["Agent<br/>one sandbox"]
  tpl --> a2["Agent<br/>one sandbox"]
  a1 --> s1["Session"]
  a1 --> s2["Session"]
  a2 --> s3["Session"]
```

How many agents and sessions you create, and for whom, is your decision: an agent per customer team and a session per conversation is common, and so is one agent with a session per pull request.

## Template

A template is a versioned, declarative definition of a kind of agent, written as one YAML or JSON document: its harness, its model, its system prompt, and its capabilities such as MCP servers and plugins.

* The server assigns versions. A new document becomes the next version of its name (`code-maintainer@1`, `@2`, ...); a document identical to the latest version returns that version.
* A version never changes once created, and every version of one name has the same harness.
* A dry run checks a document and tells you which version it would become, without storing anything.

See [Templates](https://docs.paddock.build/guides/templates.md).

## Agent

An agent is created from one exact template version and exists until you delete it. It has an ID such as `agt_01h455vb4pex5vsknk084sn02q` that you store in your own database.

* **One sandbox.** Each agent owns one E2B sandbox with its files, its memory, and the harness. All its sessions share it: a file one session writes, another can read.
* **Its own capabilities.** An agent adds its own MCP servers, plugins, environment, and settings on top of its template's, or overrides them. An agent never moves to another template version and never changes its harness.
* **Sleep and wake.** When every session of an agent has been idle for 10 minutes and no background work runs, the agent sleeps: its sandbox is paused with everything in it. The next message, or a file read, wakes it.

An agent's `status` is the state of its sandbox: `sleeping`, `waking`, `awake`, or `unavailable` when paddock could not wake it and keeps trying.

## Session

A session is an endless conversation inside an agent. It takes [messages](#message) at any time, from your backend and from your frontend alike, and processes them in the order it accepted them. It exists until you delete it.

A session is created with its own working directory (`cwd`, relative to the agent's workspace) and a system prompt that are fixed for its whole life, along with the agent's environment and permissions at that moment. See [Configuration](https://docs.paddock.build/guides/configuration.md).

Its `status` is computed from its history every time you read it:

| Status | Meaning |
| - | - |
| `idle` | Nothing is running; messages may be waiting or held |
| `running` | A turn of the session is running |
| `retrying` | The latest turn failed and a retry is planned at `retryAt` |
| `failed` | The latest turn failed, the agent gave up, and no message was sent since |
| `blocked` | The agent is unavailable and the session has work waiting |

## Message

A message is input to a session or output of a turn. Each has a stable ID (`msg_...`) and the same content live, in the stream, and in history. Its `kind` is one of:

| Kind | From |
| - | - |
| `user` | A message you sent, or that a trigger delivered |
| `assistant` | Text the agent wrote |
| `reasoning` | The model's visible reasoning |
| `tool_call`, `tool_result` | A tool the agent called and its result, sharing a `callId` |
| `unknown` | An item the harness wrote that paddock maps to no other kind, kept with its raw JSON |
| `streaming` | Live only: the whole text so far of an `assistant` message being generated, under that message's ID |

Tool calls are typed the same way for every harness: `shell`, `file_read`, `file_write`, `file_edit`, `file_patch`, `glob`, `grep`, `web_fetch`, `web_search`, `mcp`, `subagent`, `skill`, and `unknown` for any other tool. A message produced inside a subagent carries the subagent call's ID as `parentToolUseId`.

## Turn

A turn is one run of the harness over the messages waiting in a session. At most one turn runs per session at a time; messages that arrive during a turn wait, and the next turn takes all of them together.

* A **user turn** processes waiting messages. A **harness turn** is one the harness started on its own, for example when a background task finished; it consumes no message.
* A turn ends once, as `completed`, `stopped`, or `failed` with an error code. A turn the agent lost to a crash is `discarded` and its messages are processed by a new turn.
* A failed user turn is retried over the same messages, up to two more times, 10 seconds and then 60 seconds later; see [Errors](https://docs.paddock.build/platform/errors.md#turn-errors) for the exceptions. When the agent gives up, the waiting messages are held until you send the next message.
* Stopping a session ends the running turn and holds the messages waiting behind it: they start no turn on their own, and the next message you send starts one that includes them.

Each turn records its model usage and a timing breakdown of where its time went, from waking the sandbox to the reply.

## Event

Everything that happens in a session is an event in its agent's log, and a session's history is exactly its events. Each event has a `seq`, its position in the agent's log, which strictly increases across all of the agent's sessions; within one session it increases but skips numbers.

| Event type | Means |
| - | - |
| `message` | A message was stored |
| `turn.started`, `turn.ended` | A turn started, and ended with its outcome, usage, and retry decision |
| `stop.requested` | Someone stopped the session |
| `config.applied` | The session's harness took a change of the agent's configuration |
| `session.status` | A snapshot of the harness's state at a turn's end |
| `agent.unavailable`, `agent.available` | The agent could not be woken, and later could again |
| `daemon.outdated` | paddock updated its own process in the sandbox |

You read events as pages, or follow them live as a stream that resumes after the last `seq` you hold, so a client that reconnects receives every later event exactly once. See [Streaming to the browser](https://docs.paddock.build/guides/streaming.md).

## Harness

A harness is the agent program that runs inside the sandbox: [Claude Code](https://docs.paddock.build/harnesses/claude-code.md) or [Codex](https://docs.paddock.build/harnesses/codex.md), unmodified, at the version paddock pins. The template chooses it. paddock normalizes both into the same messages, tools, events, and status, so your code handles them alike, and rejects a capability a harness does not support instead of emulating it.

## Session token

A session token (`pdk_st_...`) is a short-lived credential your backend creates for one session and hands to your frontend. It grants on that session everything the server SDK can do on it, and nothing outside it. See [Authentication](https://docs.paddock.build/platform/authentication.md).

## Trigger

A trigger is a webhook URL of your project. Other services post JSON events to it, and its rules turn the events that matter into messages to an agent's sessions. See [Triggers](https://docs.paddock.build/guides/triggers.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.