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

# Templates

> Define a kind of agent as one versioned YAML document, check it with a dry run, and save an agent's configuration back as a template.

A template is one document in the style of a Kubernetes resource: `apiVersion`, `kind`, `metadata`, and `spec`. It holds everything an agent starts from and names no version; the server assigns one.

## The document

```yaml agents/code-maintainer/template.yaml theme={null}
apiVersion: paddock.build/v1
kind: Template
metadata:
  name: code-maintainer            # the version is assigned by the server
  labels:
    team: platform
spec:
  harness: claude-code
  model: claude-opus
  system_prompt: |
    You maintain Acme's web app. Keep changes small and run the tests.
  env:
    - name: NODE_ENV
      value: production
  permissions:
    allow: ["Bash(npm run test:*)"]
    deny: ["Bash(git push:*)"]
  mcp:
    - name: docs
      url: https://mcp.example.com/mcp
    - name: postgres
      command: npx
      args: ["-y", "@modelcontextprotocol/server-postgres"]
  marketplaces:
    - name: acme
      source: github.com/acme/agent-plugins
  plugins:
    - name: release-tools@acme     # its skills, subagents, hooks, and MCP servers come with it
```

| Field | Required | Meaning |
| - | - | - |
| `apiVersion` | Yes | Always `paddock.build/v1` |
| `kind` | Yes | Always `Template` |
| `metadata.name` | Yes | Lowercase letters, digits, and `-`, 1 to 64 characters |
| `metadata.labels` | No | String keys and values for your own use |
| `spec.harness` | Yes | `claude-code` or `codex`; see [Harnesses](https://docs.paddock.build/harnesses/claude-code.md) |
| `spec.model` | Yes | A model the harness runs: a catalog name such as `claude-opus`, or `provider/model` of your own provider; see [Models](https://docs.paddock.build/guides/models.md) |
| `spec.small_model` | No | Claude Code only: the model for background requests; default `claude-haiku` |
| `spec.system_prompt` | No | Text appended to the harness's own system prompt |
| `spec.env` | No | Environment variables, each a `name` and a `value` |
| `spec.permissions` | No | `allow` and `deny` rules in the harness's own syntax |
| `spec.mcp` | No | MCP servers: remote (`url`, `headers`) or run in the sandbox (`command`, `args`, `env`) |
| `spec.marketplaces` | No | Plugin marketplaces: a `name` and a public Git repository as `source` |
| `spec.plugins` | No | Plugins to install, each named `plugin@marketplace`, with `enabled` (default `true`) |

Capabilities are described in [Capabilities](https://docs.paddock.build/guides/capabilities.md), and what each setting does to a running session in [Configuration](https://docs.paddock.build/guides/configuration.md).

### YAML and JSON spelling

The same document can be written in YAML or JSON. YAML spells fields in snake\_case (`system_prompt`, `small_model`); JSON, and the TypeScript and Go types, spell them in camelCase (`systemPrompt`, `smallModel`). `apiVersion` and `kind` keep their spelling everywhere. The SDKs send a file path's YAML as it is and a document object as JSON. Both spellings of the same content get the same digest, so they are the same version.

## Create a version

```go Go theme={null}
tpl, err := client.Templates.Create(ctx, "./agents/code-maintainer/template.yaml")
if err != nil {
	return err
}
fmt.Printf("%s@%d\n", tpl.Name, tpl.Version) // code-maintainer@1
```

```python Python theme={null}
template = client.templates.create("./agents/code-maintainer/template.yaml")
print(f"{template.name}@{template.version}")  # code-maintainer@1
```

```ts TypeScript theme={null}
const template = await paddock.templates.create("./agents/code-maintainer/template.yaml");
console.log(`${template.name}@${template.version}`); // code-maintainer@1
```

| Rule | Meaning |
| - | - |
| Versions | A new document becomes its name's next version, `1` for a new name |
| Identical documents | A document whose content equals the latest version's returns that version with `200` instead of `201` |
| Immutable | A version never changes; change a template by creating its next version |
| One harness per name | Every version of a name has the same harness; a document with another one is `409 conflict` (`harness_changed`) |
| Validation | The document, every entry, and the harness's support for every kind are checked at creation; a failure is `400` or `422` and creates nothing |

Agents reference one exact version. A new version gives new agents; existing agents keep the version they were created from and change their own configuration instead.

## Check a document with a dry run

A dry run runs every check of a create and returns the version the create would return, without storing anything. Use it in CI, or while editing.

```go Go theme={null}
tpl, err := client.Templates.Create(ctx, "./agents/code-maintainer/template.yaml",
	paddock.TemplateCreate{DryRun: true})
if err != nil {
	return err // the error a create would return
}
fmt.Printf("would create %s@%d\n", tpl.Name, tpl.Version)
```

```python Python theme={null}
template = client.templates.create("./agents/code-maintainer/template.yaml", dry_run=True)
print(f"would create {template.name}@{template.version}")
```

```ts TypeScript theme={null}
const template = await paddock.templates.create("./agents/code-maintainer/template.yaml", { dryRun: true });
console.log(`would create ${template.name}@${template.version}`);
```

The answer is the latest version when the document is identical to it, otherwise the name's next version with its digest. Because nothing is stored, that version number may be taken by someone else before you create it.

A validation error names each field it found wrong in `details`, for example `spec.mcp[github].url`. See [Errors](https://docs.paddock.build/platform/errors.md).

## Create from a document in code

Pass a document instead of a path; it is sent as JSON, spelled in camelCase.

```go Go theme={null}
tpl, err := client.Templates.CreateDocument(ctx, paddock.TemplateDocument{
	Metadata: paddock.TemplateMetadata{Name: "support-bot"},
	Spec: paddock.TemplateSpec{
		Harness:      paddock.HarnessCodex,
		Model:        "gpt-5.5",
		SystemPrompt: "You answer support tickets for Acme.",
	},
})
```

```python Python theme={null}
template = client.templates.create(
    {
        "apiVersion": "paddock.build/v1",
        "kind": "Template",
        "metadata": {"name": "support-bot"},
        "spec": {
            "harness": "codex",
            "model": "gpt-5.5",
            "systemPrompt": "You answer support tickets for Acme.",
        },
    }
)
```

```ts TypeScript theme={null}
const template = await paddock.templates.create({
  apiVersion: "paddock.build/v1",
  kind: "Template",
  metadata: { name: "support-bot" },
  spec: {
    harness: "codex",
    model: "gpt-5.5",
    systemPrompt: "You answer support tickets for Acme.",
  },
});
```

## Read, list, and delete

```go Go theme={null}
detail, err := client.Templates.Get(ctx, "code-maintainer@1") // or "code-maintainer" for the latest
if err != nil {
	return err
}
fmt.Println(detail.Document.Spec.Model)

for tpl, err := range client.Templates.List(ctx, paddock.TemplateList{Name: "code-maintainer"}) {
	if err != nil {
		return err
	}
	fmt.Println(tpl.Version, tpl.Digest)
}

err = client.Templates.Delete(ctx, "code-maintainer@1")
```

```python Python theme={null}
detail = client.templates.get("code-maintainer@1")  # or "code-maintainer" for the latest
print(detail.document.spec.model)

for template in client.templates.list(name="code-maintainer"):
    print(template.version, template.digest)

client.templates.delete("code-maintainer@1")
```

```ts TypeScript theme={null}
const detail = await paddock.templates.get("code-maintainer@1"); // or "code-maintainer" for the latest
console.log(detail.document.spec.model);

for await (const template of paddock.templates.list({ name: "code-maintainer" })) {
  console.log(template.version, template.digest);
}

await paddock.templates.delete("code-maintainer@1");
```

* `get("name@version")` returns that version with its document; `get("name")` returns the latest.
* `list()` returns the latest version of each template, newest first; `list({ name })` returns every version of one name.
* Deleting a version is `409 conflict` (`template_in_use`) while any agent references it. Version numbers are never reused.

## Save an agent as a template

An agent you tuned through its own capabilities can be saved as a template. `agent.export()` returns the agent's effective configuration as a template document; creating a template from it saves it, under the template's name as its next version or under a new name as version 1. The agent itself is unchanged.

```go Go theme={null}
doc, err := agent.Export(ctx)
if err != nil {
	return err
}
doc.Metadata.Name = "code-maintainer-tuned"
tpl, err := client.Templates.CreateDocument(ctx, *doc)
```

```python Python theme={null}
document = agent.export()
document.metadata.name = "code-maintainer-tuned"
template = client.templates.create(document)
```

```ts TypeScript theme={null}
const document = await agent.export();
const template = await paddock.templates.create({
  ...document,
  metadata: { ...document.metadata, name: "code-maintainer-tuned" },
});
```

The console's template editor shows a document as a form and as YAML side by side, checked by a dry run as you type; see [Console](https://docs.paddock.build/platform/console.md).


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