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

# Quickstart

> Create an agent with a server SDK, mint a session token, and chat with the agent live from a React page.

In about five minutes you will publish a template, create an agent and a session from your backend, and talk to the agent from a browser page that shows every message and tool call as it happens. You need one paddock API key and no account at any model provider.

**1. Get an API key**

Sign in to the [console](https://console.paddock.build), open **API Keys**, and create a key. It is shown once; keep it in your backend's environment:

```bash theme={null}
export PADDOCK_API_KEY=pdk_sk_...
```

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**

```bash Go theme={null}
go get github.com/wenfengwang/paddock/sdk/go/paddock
```

```bash Python theme={null}
pip install paddock-sdk
```

```bash TypeScript theme={null}
npm install @paddock/server
```

> [!NOTE]
>
> 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](https://docs.paddock.build/sdks/typescript.md).

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

```yaml template.yaml theme={null}
apiVersion: paddock.build/v1
kind: Template
metadata:
  name: quickstart
spec:
  harness: claude-code
  model: claude-opus
  system_prompt: You are a concise assistant. Answer in a few sentences.
```

`claude-opus` is a model from paddock's catalog, so it runs on paddock's own provider account. See [Models](https://docs.paddock.build/guides/models.md) 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.

```go Go theme={null}
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/wenfengwang/paddock/sdk/go/paddock"
)

func main() {
	ctx := context.Background()
	client, err := paddock.NewClient(paddock.Options{}) // reads PADDOCK_API_KEY
	if err != nil {
		log.Fatal(err)
	}
	tpl, err := client.Templates.Create(ctx, "template.yaml")
	if err != nil {
		log.Fatal(err)
	}
	agent, err := client.Agents.Create(ctx, paddock.AgentCreate{
		Template: fmt.Sprintf("%s@%d", tpl.Name, tpl.Version),
	})
	if err != nil {
		log.Fatal(err)
	}
	session, err := agent.Sessions.Create(ctx, paddock.SessionCreate{})
	if err != nil {
		log.Fatal(err)
	}
	tok, err := session.CreateToken(ctx, paddock.TokenCreate{TTL: time.Hour})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("session:", session.ID)
	fmt.Println("token:", tok.Token)
}
```

```python Python theme={null}
from paddock import Paddock

client = Paddock()  # reads PADDOCK_API_KEY
template = client.templates.create("template.yaml")
agent = client.agents.create(template=f"{template.name}@{template.version}")
session = agent.sessions.create()
token = session.create_token(ttl=3600)
print("session:", session.id)
print("token:", token.token)
```

```ts TypeScript theme={null}
import { Paddock } from "@paddock/server";

const paddock = new Paddock(); // reads PADDOCK_API_KEY
const template = await paddock.templates.create("template.yaml");
const agent = await paddock.agents.create({ template: `${template.name}@${template.version}` });
const session = await agent.sessions.create();
const { token } = await session.createToken({ ttl: 3600 });
console.log("session:", session.id);
console.log("token:", token);
```

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:

```bash theme={null}
npm install @paddock/react
```

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

```tsx Chat.tsx theme={null}
import { useState } from "react";
import { useSession } from "@paddock/react";

export function Chat({ sessionId, token }: { sessionId: string; token: string }) {
  const { messages, status, send, stop } = useSession(sessionId, { token });
  const [text, setText] = useState("");

  return (
    <div>
      {messages.map((m) => {
        if (m.kind === "user") return <p key={m.id}>You: {m.text}</p>;
        if (m.kind === "assistant" || m.kind === "streaming") return <p key={m.id}>Agent: {m.text}</p>;
        if (m.kind === "tool_call") return <pre key={m.id}>{m.toolCall.tool}</pre>;
        return null;
      })}
      <form
        onSubmit={(e) => {
          e.preventDefault();
          void send(text);
          setText("");
        }}
      >
        <input value={text} onChange={(e) => setText(e.target.value)} />
        <button type="submit">Send</button>
        {status === "running" && (
          <button type="button" onClick={() => void stop()}>
            Stop
          </button>
        )}
      </form>
    </div>
  );
}
```

Render `<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.

In a real application your backend creates sessions and tokens on demand and returns them from its own endpoint. Continue with [Agents and sessions](https://docs.paddock.build/guides/agents-and-sessions.md) and [Streaming to the browser](https://docs.paddock.build/guides/streaming.md).


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