Skip to main content
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. 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.

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 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. Its status is computed from its history every time you read it:

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: 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 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. 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.

Harness

A harness is the agent program that runs inside the sandbox: Claude Code or Codex, 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.

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.