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

# Models and BYOK

> Run agents on paddock's model catalog with no provider account, or on your own Anthropic and OpenAI providers with your own keys.

Every template and agent names one model. It comes from one of two sources:

| Source | Named | Billed | Key |
| - | - | - | - |
| **Platform models**: paddock's catalog | A catalog name, such as `claude-opus` | With the rest of paddock | paddock's own |
| **Project models**: your own providers | `provider/model`, such as `acme/claude-sonnet-5-5` | By your provider, on your account | Yours, stored encrypted in paddock |

Either way the harness reaches models only through paddock's model endpoint, which routes each request by the model name it carries. No provider key, paddock's or yours, is ever present in a sandbox.

## The catalog

| Catalog name | Harness | API |
| - | - | - |
| `claude-opus` | Claude Code | Anthropic Messages |
| `claude-sonnet` | Claude Code | Anthropic Messages |
| `claude-haiku` | Claude Code | Anthropic Messages |
| `gpt-5.5` | Codex | OpenAI Responses |

Each model runs on one harness: Claude Code runs Anthropic models and Codex runs OpenAI models. Naming a model of another harness in a template or an agent is `400`.

`models.list()` returns every model your project can use, platform models first, then each of your providers' models, in one page:

```go Go theme={null}
for m, err := range client.Models.List(ctx) {
	if err != nil {
		return err
	}
	fmt.Println(m.Name, m.Harness, m.Source)
}
```

```python Python theme={null}
for m in client.models.list():
    print(m.name, m.harness, m.source)
```

```ts TypeScript theme={null}
for await (const m of paddock.models.list()) {
  console.log(m.name, m.harness, m.source);
}
```

## Bring your own provider

Add a model provider to your project with your own key, and the models you choose from it become project models.

| Kind | Protocol and harness | Base URL |
| - | - | - |
| `anthropic` | Anthropic Messages API, for Claude Code | `https://api.anthropic.com`, fixed |
| `openai` | OpenAI Responses API, for Codex | `https://api.openai.com/v1`, fixed |
| `anthropic-compatible` | Anthropic Messages API, for Claude Code | Yours: an `https` URL |
| `openai-compatible` | OpenAI Responses API, for Codex | Yours: an `https` URL that serves the Responses API |

```go Go theme={null}
provider, err := client.ModelProviders.Create(ctx, paddock.ProviderCreate{
	Name:   "acme",
	Kind:   paddock.ProviderKindAnthropic,
	APIKey: os.Getenv("ANTHROPIC_API_KEY"),
	Models: []string{"claude-sonnet-5-5"},
})
if err != nil {
	return err
}
fmt.Println(provider.KeyPreview, provider.Models[0].Name) // sk-a…x9Qz acme/claude-sonnet-5-5
```

```python Python theme={null}
import os

provider = client.model_providers.create(
    {
        "name": "acme",
        "kind": "anthropic",
        "apiKey": os.environ["ANTHROPIC_API_KEY"],
        "models": ["claude-sonnet-5-5"],
    }
)
print(provider.key_preview, provider.models[0].name)  # sk-a…x9Qz acme/claude-sonnet-5-5
```

```ts TypeScript theme={null}
const provider = await paddock.modelProviders.create({
  name: "acme",
  kind: "anthropic",
  apiKey: process.env.ANTHROPIC_API_KEY ?? "",
  models: ["claude-sonnet-5-5"],
});
console.log(provider.keyPreview, provider.models[0]?.name); // sk-a…x9Qz acme/claude-sonnet-5-5
```

| Field | Rule |
| - | - |
| `name` | Lowercase letters, digits, and `-`, 1 to 32 characters, unique in the project; it never changes |
| `kind` | One of the four kinds above; it fixes the protocol and so the harness |
| `baseUrl` | Required for the compatible kinds: `https`, no query or fragment, at most 512 bytes. Refused for `anthropic` and `openai` |
| `apiKey` | 8 to 1,024 printable characters without spaces. Write-only: responses carry only `keyPreview` |
| `models` | Up to 100 model IDs, as the provider names them |
| `testModel` | The model for a one-token test request when the provider lists no models; default the first of `models` |

### How the key is verified

Creating a provider, changing its key or base URL, and both test operations verify the key first, and a create or update whose verification fails changes nothing:

1. List the provider's models with the key (`GET /v1/models` for Anthropic, `GET /models` for OpenAI). This spends no tokens.
2. If a compatible endpoint lists no models, send one minimal request to `testModel`.

Test a key before you store it, or test a stored provider again:

```go Go theme={null}
result, err := client.ModelProviders.TestDraft(ctx, paddock.ProviderDraft{
	Kind:    paddock.ProviderKindAnthropicCompatible,
	BaseURL: "https://llm.example.com",
	APIKey:  os.Getenv("RELAY_KEY"),
})
if err != nil {
	return err
}
fmt.Println(result.Ok, result.Method, result.Models)

stored, err := client.ModelProviders.Test(ctx, "acme", paddock.ProviderTestOptions{})
```

```python Python theme={null}
import os

result = client.model_providers.test(
    {"kind": "anthropic-compatible", "baseUrl": "https://llm.example.com", "apiKey": os.environ["RELAY_KEY"]}
)
print(result.ok, result.method, result.models)

stored = client.model_providers.test("acme")
```

```ts TypeScript theme={null}
const result = await paddock.modelProviders.test({
  kind: "anthropic-compatible",
  baseUrl: "https://llm.example.com",
  apiKey: process.env.RELAY_KEY ?? "",
});
console.log(result.ok, result.method, result.models);

const stored = await paddock.modelProviders.test("acme");
```

A test answers `{ ok, method, models, error }`: `method` is `list` or `request`, `models` the IDs the provider listed, and `error` what the provider answered when `ok` is false. Testing a stored provider also records its status.

## Use a project model

Name it `provider/model` wherever a model is named: a template's `model` and `small_model`, or an agent's model settings.

```yaml theme={null}
spec:
  harness: claude-code
  model: acme/claude-sonnet-5-5
  small_model: claude-haiku            # platform and project models mix freely
```

```go Go theme={null}
_, err := agent.ModelSetting.Set(ctx, "acme/claude-sonnet-5-5")
```

```python Python theme={null}
agent.model_setting.set("acme/claude-sonnet-5-5")
```

```ts TypeScript theme={null}
await agent.modelSetting.set("acme/claude-sonnet-5-5");
```

* The name is split at the first `/`: the provider, then the model ID sent to the provider as it is.
* A name with `/` that is not a model of one of your providers, or a model of another harness, is `400`.
* A model change reaches running sessions between turns; a turn always finishes on the model it started with.
* A new key or base URL applies from the next request.

## Failures

There is no fallback: a request for a project model goes only to that provider, with your key.

| The provider answers | The turn | The provider |
| - | - | - |
| `401` or `403` | Fails with `model_auth`, naming the provider | Marked `failing`, with the answer in `lastError` |
| `429`, a `5xx`, or nothing | Fails with `model_unavailable`, and is retried | Unchanged |
| Success while `failing` | Runs | Marked `ok` again |

Fix the key with `modelProviders.update(name, { apiKey })`; the next successful request or test marks the provider `ok`.

## Manage providers

```go Go theme={null}
for p, err := range client.ModelProviders.List(ctx, paddock.ModelProviderList{}) {
	if err != nil {
		return err
	}
	fmt.Println(p.Name, p.Status)
}

models := []string{"claude-sonnet-5-5", "claude-opus-5-5"}
_, err := client.ModelProviders.Update(ctx, "acme", paddock.ProviderUpdate{Models: &models})
if err != nil {
	return err
}
err = client.ModelProviders.Delete(ctx, "acme")
```

```python Python theme={null}
for p in client.model_providers.list():
    print(p.name, p.status)

client.model_providers.update("acme", {"models": ["claude-sonnet-5-5", "claude-opus-5-5"]})
client.model_providers.delete("acme")
```

```ts TypeScript theme={null}
for await (const p of paddock.modelProviders.list()) {
  console.log(p.name, p.status);
}

await paddock.modelProviders.update("acme", { models: ["claude-sonnet-5-5", "claude-opus-5-5"] });
await paddock.modelProviders.delete("acme");
```

* `update` changes only the fields you send; `models` replaces the whole list.
* Removing a model, or deleting a provider, that a template version or a live agent names as its model or small model is `409 conflict` (`model_in_use`).

The console's **Models** page does the same, and its model pickers offer platform and project models together; see [Console](https://docs.paddock.build/platform/console.md).


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