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

# Introduction

> paddock runs persistent agents on Claude Code and Codex, and gets their live state into your own UI.

paddock is the fastest way to build an agent application on Claude Code and Codex. It is a hosted backend that runs each agent in its own E2B sandbox, server SDKs in Go, Python, and TypeScript that control agents and sessions from your backend, and a browser client SDK that turns a session ID and a token into live state in your frontend.

The agents worth building carry work instead of answering one request: they run for hours, keep going while their user is away, and take new input at any moment. paddock makes that **persistent agent** the unit:

* **Endless sessions.** A session takes messages at any time, queues the ones that arrive during a turn, and processes them in order. It never ends on its own.
* **Sleep and wake.** An agent whose sessions are all idle sleeps, and the next message wakes it with its conversations and files exactly where they were.
* **Recovery.** A turn lost to a sandbox failure is run again over the same messages; a turn that stops making progress is ended by a watchdog and retried.
* **Models included.** Agents run on models paddock provides, with no provider account of your own, or on your own Anthropic or OpenAI providers and keys. No provider key ever enters a sandbox.
* **Live state for your UI.** Every message, tool call, and turn of a session is an event, streamed live and replayed after a reconnect, so your frontend writes no streaming, reconnection, or state code.
* **Triggers.** A webhook URL turns another service's events, such as a GitHub pull request, into messages for an agent, with no server of yours in between.

## How it fits together

```mermaid theme={null}
flowchart LR
  yaml["template.yaml"] -- "templates.create" --> tpl["Template name@version"]
  tpl -- "agents.create" --> agent["Agent: one sandbox"]
  agent -- "sessions.create" --> session["Session"]
  session -- "createToken" --> browser["Your frontend: useSession"]
```

Your backend publishes a **template**, a versioned YAML definition of a kind of agent. It creates **agents** from it, each with its own sandbox, and opens **sessions** inside them. It hands a session ID and a short-lived **session token** to your frontend, which shows the session live.

```ts theme={null}
// Your backend
const agent = await paddock.agents.create({ template: "code-maintainer@1" });
const session = await agent.sessions.create({ metadata: { userId: "u_7" } });
const { token } = await session.createToken({ ttl: 3600 });
```

```tsx theme={null}
// Your frontend
const { messages, status, send } = useSession(sessionId, { token });
```

> [card] [Quickstart](https://docs.paddock.build/quickstart.md)
>
> Create an agent and chat with it from a browser in about five minutes.

> [card] [Core concepts](https://docs.paddock.build/concepts.md)
>
> Templates, agents, sessions, turns, events, and harnesses.

> [card] [SDKs](https://docs.paddock.build/sdks/typescript.md)
>
> Go, Python, and TypeScript on the server; TypeScript and React in the browser.

> [card] [API reference](https://docs.paddock.build/api-reference/introduction.md)
>
> Every operation of the HTTP API.

## Harnesses

paddock runs the harnesses unmodified, each at a pinned version:

| Harness | Models | Strengths |
| - | - | - |
| [Claude Code](https://docs.paddock.build/harnesses/claude-code.md) | Anthropic models | Skills, hooks, plugins, subagents, workflows, and MCP |
| [Codex](https://docs.paddock.build/harnesses/codex.md) | OpenAI models | The strongest harness on OpenAI models, with plugins, skills, and MCP |

You keep the mapping between your own users and paddock's agents and sessions: store agent and session IDs next to your records, the way you store customer IDs from a payments provider.


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