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{
    Alias:       "data-analysis",
    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
`Alias`	`string`	Required. The template’s name; sandboxes are created from it with `WithTemplate(Alias)`. Lowercase letters, digits and hyphens, and not a built-in template’s name
`BaseImage`	`string`	Base Docker image tag
`RunCmds`	`[]string`	Commands executed during the build
`Copies`	`[]CopyItem`	Files to copy into the template. Not supported yet: builds cannot upload local files, so `BuildTemplate` rejects a spec that sets it
`Envs`	`map[string]string`	Environment variables for commands run in sandboxes created from the template; a sandbox’s own envs win on conflict
`AptPackages`	`[]string`	Apt packages to install
`StartCmd`	`string`	Command to run when the sandbox starts. Recorded with the template, but not yet run at boot
`Dockerfile`	`string`	Raw Dockerfile (alternative to structured fields)
`DiskMB`	`int`	Disk size in MB: 512, 2048, 4096, 8192 or 16384 (default 4096); other sizes round up

`CopyItem`

type CopyItem struct {
    Src  string
    Dst  string
    Mode string
}

`declaw.BuildTemplate()`

Build a new template and wait for the build to complete. Builds usually take several minutes; bound the wait with ctx.

spec := declaw.TemplateSpec{
    Alias:       "data-analysis",
    AptPackages: []string{"python3-pip"},
    RunCmds:     []string{"pip3 install pandas"},
}

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
defer cancel()

build, err := declaw.BuildTemplate(ctx, spec)
if err != nil {
    var buildErr *declaw.BuildError
    if errors.As(err, &buildErr) {
        fmt.Println(strings.Join(buildErr.Logs, "\n")) // the failed build's full output
    }
    log.Fatal(err)
}
fmt.Println("Template ID:", build.TemplateID)

Returns (*BuildInfo, error). On success Status is declaw.BuildStatusCompleted. A failed build returns a *BuildError whose message quotes the end of the build output and whose Logs holds all of it. If ctx ends first, the error is ctx.Err() and the returned BuildInfo still carries the BuildID: the build keeps running, and GetBuildStatus or WaitForBuild follows it. Status checks that fail temporarily (5xx, 429, no response) are retried for up to two minutes.

`declaw.WaitForBuild()`

Wait for a build started with BuildTemplateBackground to finish, passing each new line of build output to a callback. It returns like BuildTemplate.

build, err := declaw.BuildTemplateBackground(ctx, spec)
if err != nil {
    log.Fatal(err)
}
fmt.Println("Build started:", build.BuildID)

done, err := declaw.WaitForBuild(ctx, build.BuildID, func(line string) {
    fmt.Println(line)
})

The server keeps the newest 2,000 lines of a build’s output; if more arrive between two checks, a ... [earlier build output truncated] line marks the gap. 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) with Status declaw.BuildStatusBuilding.

`declaw.RebuildTemplate()`

Needs github.com/declaw-ai/declaw-go v0.8.0 or later. Upgrade with go get github.com/declaw-ai/declaw-go@latest.

Retry a template whose build failed, and wait for the rebuild like BuildTemplate. The rebuild reuses the template’s stored spec.

build, err := declaw.BuildTemplate(ctx, spec)
var buildErr *declaw.BuildError
if errors.As(err, &buildErr) {
    // The failed template keeps its alias; retry it by ID.
    build, err = declaw.RebuildTemplate(ctx, buildErr.TemplateID)
}

Templates are immutable once built, so a ready template, or one whose build is still running, is refused with *ConflictError. A failed template keeps its alias: BuildTemplate with the same alias is refused with a *ConflictError whose message names the template to rebuild. Returns (*BuildInfo, error) — the completed build, a *BuildError for a failed one, or ctx’s error once ctx ends (the build keeps running).

`declaw.RebuildTemplateBackground()`

Queue a rebuild of a failed template and return as soon as the server has accepted it, with status building. Follow it with WaitForBuild or GetBuildStatus.

build, err := declaw.RebuildTemplateBackground(ctx, "tpl-1234567890abcdef")
fmt.Println("Rebuild started:", build.BuildID)

done, err := declaw.WaitForBuild(ctx, build.BuildID, func(line string) {
    fmt.Println(line)
})

Returns (*BuildInfo, error)

`declaw.GetBuildStatus()`

Poll the status of a background build.

status, err := declaw.GetBuildStatus(ctx, build.BuildID)
fmt.Println(status.Status) // "building", "completed" or "failed"
fmt.Println(status.Logs)   // build output so far

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 // BuildStatusBuilding, BuildStatusCompleted or BuildStatusFailed
    TemplateID string
    Logs       []string // build output; empty in the response to starting a build
}

`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 == declaw.BuildStatusCompleted || status.Status == declaw.BuildStatusFailed {
        break
    }
    time.Sleep(3 * time.Second)
}

Python SDK

TypeScript SDK

Go SDK

TemplateSpec

`CopyItem`

`declaw.BuildTemplate()`

`declaw.WaitForBuild()`

`declaw.BuildTemplateBackground()`

`declaw.RebuildTemplate()`

`declaw.RebuildTemplateBackground()`

`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.WaitForBuild()

​declaw.BuildTemplateBackground()

​declaw.RebuildTemplate()

​declaw.RebuildTemplateBackground()

​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.WaitForBuild()`

`declaw.BuildTemplateBackground()`

`declaw.RebuildTemplate()`

`declaw.RebuildTemplateBackground()`

`declaw.GetBuildStatus()`

`declaw.ListTemplates()`

`declaw.GetTemplate()`

`declaw.DeleteTemplate()`

Data models

`BuildInfo`

`TemplateInfo`

Using a template in Create()

Polling a background build