Templates

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.

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`

type CopyItem struct {
    Src  string
    Dst  string
    Mode string
}

`declaw.BuildTemplate()`

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

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.

build, err := declaw.BuildTemplateBackground(ctx, spec)
fmt.Println("Build started:", build.BuildID)

Returns (*BuildInfo, error)

`declaw.GetBuildStatus()`

Poll the status of a background build.

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.

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.

tmpl, err := declaw.GetTemplate(ctx, "tmpl-abc123")

Returns (*TemplateInfo, error)

`declaw.DeleteTemplate()`

Delete a template by its ID.

err := declaw.DeleteTemplate(ctx, "tmpl-abc123")

Returns error

Data models

`BuildInfo`

type BuildInfo struct {
    BuildID    string
    Status     string // "queued", "building", "success", or "failed"
    TemplateID string
}

`TemplateInfo`

type TemplateInfo struct {
    TemplateID string
    Alias      string
    CreatedAt  string
}

Using a template in Create()

Once a template is built, reference it by alias:

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

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)
}

Python SDK

TypeScript SDK

Go SDK

TemplateSpec

`CopyItem`

`declaw.BuildTemplate()`

`declaw.BuildTemplateBackground()`

`declaw.GetBuildStatus()`

`declaw.ListTemplates()`

`declaw.GetTemplate()`

`declaw.DeleteTemplate()`

Data models

`BuildInfo`

`TemplateInfo`

Using a template in Create()

Polling a background build

​TemplateSpec

​CopyItem

​declaw.BuildTemplate()

​declaw.BuildTemplateBackground()

​declaw.GetBuildStatus()

​declaw.ListTemplates()

​declaw.GetTemplate()

​declaw.DeleteTemplate()

​Data models

​BuildInfo

​TemplateInfo

​Using a template in Create()

​Polling a background build

TemplateSpec

`CopyItem`

`declaw.BuildTemplate()`

`declaw.BuildTemplateBackground()`

`declaw.GetBuildStatus()`

`declaw.ListTemplates()`

`declaw.GetTemplate()`

`declaw.DeleteTemplate()`

Data models

`BuildInfo`

`TemplateInfo`

Using a template in Create()

Polling a background build