> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bonya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> The image a sandbox is created from

Every sandbox starts from a **template**. The deployment publishes an immutable
catalog of template IDs and versions at `GET /v1/templates`.

## Discovering templates

The catalog is shared by every caller in the deployment and is not scoped to
an organization. Each entry includes its `template_id`, immutable `version`,
digest, and optional metadata: a description, base OS, preinstalled language
stacks, and available agent CLIs.

```shell cURL theme={null}
curl -s "https://api.bonya.ai/v1/templates" \
  -H "Authorization: Bearer $BONYA_API_KEY"
```

```ts TypeScript theme={null}
const templates = await client.listTemplates();
for (const template of templates) {
  console.log(template.id, template.version, template.isDefault, template.metadata.os);
}
```

```python Python theme={null}
templates = client.list_templates()
for template in templates:
    print(template.id, template.version, template.is_default, template.metadata.os)
```

```go Go theme={null}
templates, err := client.ListTemplates(ctx)
for _, template := range templates {
    fmt.Println(template.ID, template.Version, template.IsDefault, template.Metadata.OS)
}
```

There's no `bonya template` CLI command; `bonya create` offers the catalog interactively instead. **MCP:** the `template_list` tool exposes the same catalog.

```json theme={null}
{
  "templates": [{
    "template_id": "bonya-dev",
    "version": "2026.08",
    "digest": "sha256:…",
    "is_default": true,
    "metadata": {
      "description": "Ubuntu base image with session support.",
      "os": "ubuntu",
      "os_version": "24.04",
      "stacks": [{ "name": "go", "version": "1.25" }],
      "agent_cli_support": ["codex"]
    }
  }]
}
```

`is_default` applies **within a template ID**: it identifies the version the
service resolves when a request names that ID but omits its version. It is not
a deployment-wide default, so more than one catalog entry can have
`is_default: true`.

## Creating from a template

**template\_id** `string`

Identifies the image to create the sandbox from. Omit it, along with
`template_version`, to use the deployment's configured default template.

**template\_version** `string`

Optionally pins a specific immutable version. It is only meaningful with a
`template_id`.

Both fields are set on [sandbox create](https://docs.bonya.ai/concepts/sandboxes.md#creating-a-sandbox)
(`POST /v1/sandbox`). The created `Sandbox` echoes the resolved
`template_id` and `template_version`.

```json theme={null}
{ "template_id": "bonya-dev" }
```

The request above uses the selected template ID's default version. To use the
deployment default template instead, send an empty body (or omit both template
fields):

```json theme={null}
{}
```

If the deployment has no configured default, `template_id` is required.

> [!NOTE]
>
> A job's `new_sandbox` spec accepts the same `template_id`/`template_version` fields as sandbox create, and can omit them the same way to fall back to the deployment default. See [Jobs](https://docs.bonya.ai/sdks/go/usage.md#jobs) (or the equivalent page for your SDK) for the job spec shape.

## Related

> [card] [Sandboxes](https://docs.bonya.ai/concepts/sandboxes.md)


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