Templates

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.

curl -s "https://api.bonya.ai/v1/templates" \
  -H "Authorization: Bearer $BONYA_API_KEY"

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

templates = client.list_templates()
for template in templates:
    print(template.id, template.version, template.is_default, template.metadata.os)

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.

{
  "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

string

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

string

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

Both fields are set on sandbox create (POST /v1/sandbox). The created Sandbox echoes the resolved template_id and template_version.

{ "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):

{}

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

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 (or the equivalent page for your SDK) for the job spec shape.

Get started

Tutorials

Core concepts

API essentials

Guides

Discovering templates

Creating from a template

Sandboxes

​Discovering templates

​Creating from a template

​Related

Sandboxes

Discovering templates

Creating from a template

Related