Skip to main content
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,
}
FieldTypeDescription
BaseImagestringBase Docker image tag
RunCmds[]stringCommands executed during the build
Copies[]CopyItemFiles to copy into the template
Envsmap[string]stringEnvironment variables baked in
AptPackages[]stringApt packages to install
StartCmdstringCommand run when the sandbox starts
DockerfilestringRaw Dockerfile (alternative to structured fields)
DiskMBintDisk 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)
}