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

# Templates

> Build and manage custom sandbox templates using the Go SDK's BuildTemplate, ListTemplates, and TemplateSpec.

```go theme={null}
import "github.com/declaw-ai/declaw-go"
```

Templates let you pre-build sandbox images with specific packages, files, and environment variables installed. Once built, a template can be referenced by alias in `Create(WithTemplate("my-template"))` to boot sandboxes that start from a known state.

## TemplateSpec

`TemplateSpec` defines how to build a sandbox template.

```go theme={null}
spec := declaw.TemplateSpec{
    BaseImage:   "ubuntu:22.04",
    AptPackages: []string{"python3", "python3-pip", "curl"},
    RunCmds:     []string{"pip3 install pandas numpy matplotlib"},
    Envs:        map[string]string{"PYTHONPATH": "/home/user"},
    StartCmd:    "sleep infinity",
    DiskMB:      2048,
}
```

| Field         | Type                | Description                                       |
| ------------- | ------------------- | ------------------------------------------------- |
| `BaseImage`   | `string`            | Base Docker image tag                             |
| `RunCmds`     | `[]string`          | Commands executed during the build                |
| `Copies`      | `[]CopyItem`        | Files to copy into the template                   |
| `Envs`        | `map[string]string` | Environment variables baked in                    |
| `AptPackages` | `[]string`          | Apt packages to install                           |
| `StartCmd`    | `string`            | Command run when the sandbox starts               |
| `Dockerfile`  | `string`            | Raw Dockerfile (alternative to structured fields) |
| `DiskMB`      | `int`               | Disk size in megabytes                            |

### `CopyItem`

```go theme={null}
type CopyItem struct {
    Src  string
    Dst  string
    Mode string
}
```

***

## `declaw.BuildTemplate()`

Build a new template and wait for the build to complete.

```go theme={null}
spec := declaw.TemplateSpec{
    AptPackages: []string{"python3-pip"},
    RunCmds:     []string{"pip3 install pandas"},
}

build, err := declaw.BuildTemplate(ctx, spec)
fmt.Println("Template ID:", build.TemplateID)
fmt.Println("Status:", build.Status)
```

**Returns** `(*BuildInfo, error)`

***

## `declaw.BuildTemplateBackground()`

Start a template build and return immediately without waiting for completion.

```go theme={null}
build, err := declaw.BuildTemplateBackground(ctx, spec)
fmt.Println("Build started:", build.BuildID)
```

**Returns** `(*BuildInfo, error)`

***

## `declaw.GetBuildStatus()`

Poll the status of a background build.

```go theme={null}
status, err := declaw.GetBuildStatus(ctx, build.BuildID)
fmt.Println(status.Status) // "queued", "building", "success", or "failed"
```

**Returns** `(*BuildInfo, error)`

***

## `declaw.ListTemplates()`

List all templates owned by the caller.

```go theme={null}
templates, err := declaw.ListTemplates(ctx)
for _, t := range templates {
    fmt.Println(t.TemplateID, t.Alias, t.CreatedAt)
}
```

**Returns** `([]TemplateInfo, error)`

***

## `declaw.GetTemplate()`

Get information about a specific template.

```go theme={null}
tmpl, err := declaw.GetTemplate(ctx, "tmpl-abc123")
```

**Returns** `(*TemplateInfo, error)`

***

## `declaw.DeleteTemplate()`

Delete a template by its ID.

```go theme={null}
err := declaw.DeleteTemplate(ctx, "tmpl-abc123")
```

**Returns** `error`

***

## Data models

### `BuildInfo`

```go theme={null}
type BuildInfo struct {
    BuildID    string
    Status     string // "queued", "building", "success", or "failed"
    TemplateID string
}
```

### `TemplateInfo`

```go theme={null}
type TemplateInfo struct {
    TemplateID string
    Alias      string
    CreatedAt  string
}
```

***

## Using a template in Create()

Once a template is built, reference it by alias:

```go theme={null}
sbx, err := declaw.Create(ctx,
    declaw.WithTemplate("data-analysis"),
    declaw.WithTimeout(300),
)

// pandas is already installed
result, _ := sbx.Commands.Run(ctx, `python3 -c "import pandas; print(pandas.__version__)"`)
fmt.Println(result.Stdout)
sbx.Kill(ctx)
```

***

## Polling a background build

```go theme={null}
build, _ := declaw.BuildTemplateBackground(ctx, spec)

for {
    status, err := declaw.GetBuildStatus(ctx, build.BuildID)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Status:", status.Status)
    if status.Status == "success" || status.Status == "failed" {
        break
    }
    time.Sleep(3 * time.Second)
}
```