1
Get an API key
Sign in to the console, open API Keys, and create a key. It is shown once; keep it in your backend’s environment:Every server SDK reads
PADDOCK_API_KEY when you do not pass a key. Never ship this key to a browser; the browser gets a session token instead.2
Install a server SDK
The packages are not published to npm and PyPI yet. Until they are, build them from the
sdk/ directory of the paddock repository; see SDKs.3
Write a template
A template is a versioned YAML document that defines a kind of agent: its harness, its model, and its system prompt. Save this as
template.yaml:template.yaml
claude-opus is a model from paddock’s catalog, so it runs on paddock’s own provider account. See Models for the others.4
Create an agent and a session
This script publishes the template, creates an agent from it, opens a session, and mints a one-hour session token for the browser.Creating an agent returns at once; its sandbox is created the first time a session needs it. Run the script and keep the session ID and the token it prints.
5
Show the session in React
Install the React bindings in your frontend:Render
useSession loads the session’s history, follows its live stream, and folds both into one state object. Messages being generated arrive as streaming entries whose text grows until the finished assistant message replaces them.Chat.tsx
<Chat sessionId="ses_..." token="pdk_st_..." /> with the values the script printed and send a message. The first turn wakes the agent’s new sandbox, so it takes a few seconds longer than the ones after it.What just happened
- The template became version 1 of
quickstart. Creating the same document again returns the same version; a changed document becomes version 2. - The agent owns one sandbox, created on first use. When all its sessions are idle for a while it sleeps, and the next message wakes it with its conversation and files intact.
- The browser holds only the session token, which works on that one session and nothing else, and expires after the hour you asked for.
- Your backend can send to the same session at any time with
session.send(text), for example when a build fails. Messages from both sides are processed in the order paddock accepted them.