Templates

from declaw import Template, TemplateBase, BuildInfo, TemplateBuildStatus, CopyItem

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 Sandbox.create(template="my-template") to boot sandboxes that start from a known state.

TemplateBase

TemplateBase is a fluent builder for defining the contents of a template. Build up the definition by chaining methods, then pass it to Template.build().

from declaw import TemplateBase

template = (
    TemplateBase()
    .from_base_image("ubuntu:22.04")
    .apt_install("python3", "python3-pip", "curl")
    .run_cmd(["pip3", "install", "pandas", "numpy", "matplotlib"])
    .set_envs({"PYTHONPATH": "/home/user"})
    .set_start_cmd("sleep infinity")
)

Methods

`.from_base_image(image)`

Set the base Docker image.

str

default:"'ubuntu:22.04'"

Docker image tag to use as the base.

Returns TemplateBase (for chaining)

`.apt_install(*packages)`

Install apt packages.

template.apt_install("git", "curl", "jq")

str

required

One or more package names to install via apt-get install.

Returns TemplateBase

`.run_cmd(cmds)`

Add a shell command to run during the build (equivalent to a Dockerfile RUN).

template.run_cmd(["pip3", "install", "torch", "--index-url", "https://download.pytorch.org/whl/cpu"])

list[str]

required

Command as a list of strings (the executable and its arguments).

Returns TemplateBase

`.copy(src, dst, mode)`

Copy a local file into the template image at build time.

Not supported yet. A template build cannot upload local files, so building a template that uses copy() raises InvalidArgumentError. Fetch the file in a run_cmd step (for example with curl), or build from a Dockerfile with from_dockerfile().

str

required

Local path to the file to copy.

str

required

Destination path inside the image.

int | None

default:"None"

Unix file permission bits (e.g. 0o755 for executable).

Returns TemplateBase

`.set_envs(envs)`

Set environment variables for commands run in sandboxes created from the template. A sandbox’s own envs win on conflict.

template.set_envs({"APP_ENV": "production", "PORT": "8080"})

dict[str, str]

required

Key-value pairs to set as environment variables.

Returns TemplateBase

`.set_start_cmd(cmd, ready_check)`

Set a command to run when the sandbox boots.

The start command is recorded with the template but is not yet run when a sandbox boots. Start long-running processes with sandbox.commands.run(..., background=True) after creating the sandbox.

template.set_start_cmd("python3 /app/server.py")

str

required

Shell command to execute on sandbox start.

Any | None

default:"None"

Optional readiness probe configuration. Reserved for future use.

Returns TemplateBase

`.to_dict()`

Serialize the template definition to a dict suitable for the API. Returns dict

Template

Template is a static class for building and querying templates via the API.

`Template.build()`

Build a template and wait for the build to finish. Builds usually take several minutes; while waiting, each new line of build output is passed to on_build_logs.

from declaw import Template, TemplateBase

template = (
    TemplateBase()
    .apt_install("python3-pip")
    .run_cmd(["pip3", "install", "pandas"])
)

build_info = Template.build(
    template=template,
    alias="data-analysis",
    cpu_count=2,
    memory_mb=2048,
    on_build_logs=print,
    api_key="your-api-key",
    domain="api.declaw.ai",
)
print("Template ID:", build_info.template_id)

TemplateBase

required

The template definition to build.

str

required

Human-readable name for the template. Used as the template parameter in Sandbox.create().

int

default:"1"

Number of CPUs for the build worker.

int

default:"512"

Memory in MB for the build worker.

int

default:"4096"

Disk size in MB for the template: 512, 2048, 4096, 8192 or 16384. Other sizes round up to the next one.

Callable[[str], None] | None

default:"None"

Called with each new line of build output while the build runs. The server keeps the newest 2,000 lines; if more arrive between two checks, a ... [earlier build output truncated] line marks the gap.

float

default:"3600"

Seconds to wait for the build to finish. If it is still running, TimeoutError is raised; the build keeps running, and get_build_status() follows it.

str | None

default:"$DECLAW_API_KEY"

API key override.

str | None

default:"$DECLAW_DOMAIN"

Domain override.

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns BuildInfo with status completed. Raises

BuildError — the build failed. The message quotes the end of the build output; .build_id and .logs hold the rest.
TimeoutError — the build was still running after build_timeout seconds.
The error from a status check that keeps failing: temporary failures (5xx, 429, no response) are retried for up to two minutes, other errors (e.g. NotFoundError) end the wait at once. The build itself keeps running.
InvalidArgumentError — the template uses copy(), which is not supported yet.

`Template.build_in_background()`

Submit a template build and return immediately without waiting for it to finish.

build_info = Template.build_in_background(
    template=template,
    alias="my-template",
    api_key="your-api-key",
    domain="api.declaw.ai",
)
print("Build started:", build_info.build_id)

Parameters are the same as Template.build() except on_build_logs and build_timeout, which only apply while waiting. Returns BuildInfo with status building.

`Template.rebuild()`

Needs declaw 1.7.0 or later. Upgrade with pip install -U declaw.

Retry a template whose build failed, and wait for the rebuild like build().

from declaw import Template
from declaw.exceptions import BuildError

try:
    Template.build(template, alias="my-template")
except BuildError as err:
    # The failed template keeps its alias; retry it by ID.
    info = Template.rebuild(err.template_id, on_build_logs=print)
    print(info.status)  # "completed"

The rebuild reuses the template’s stored spec. Templates are immutable once built, so a ready template, or one whose build is still running, is refused with ConflictError. Building the same alias again is also refused with a ConflictError whose message names the template to rebuild.

str

required

The template to rebuild. Only a template whose last build failed.

Callable[[str], None] | None

default:"None"

Called with each new line of build output while waiting.

str | None

default:"$DECLAW_API_KEY"

API key override.

str | None

default:"$DECLAW_DOMAIN"

Domain override.

float | None

default:"None"

Per-request HTTP timeout in seconds.

float

default:"3600"

Seconds to wait for the build to finish. It keeps running after a TimeoutError; follow it with get_build_status().

Returns BuildInfo with status completed. Raises BuildError (the rebuild failed; the error carries its logs), ConflictError (the template is not in the failed state), TimeoutError.

`Template.rebuild_in_background()`

Queue a rebuild of a failed template and return as soon as the server has accepted it, with status building. Follow it with get_build_status().

info = Template.rebuild_in_background("tpl-1234567890abcdef")
print("Rebuild started:", info.build_id)

Parameters are the same as Template.rebuild() except on_build_logs and build_timeout, which only apply while waiting. Returns BuildInfo with status building.

`Template.get_build_status()`

Poll the status of a background build.

import time

build_info = Template.build_in_background(template, "my-template", api_key="YOUR_API_KEY", domain="api.declaw.ai")

while True:
    status = Template.get_build_status(
        build_id=build_info.build_id,
        api_key="your-api-key",
        domain="api.declaw.ai",
    )
    print(status.status, status.logs[-1] if status.logs else "")
    if status.status in ("completed", "failed"):
        break
    time.sleep(3)

str

required

Build ID from a previous build() or build_in_background() call.

str | None

default:"$DECLAW_API_KEY"

API key override.

str | None

default:"$DECLAW_DOMAIN"

Domain override.

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns TemplateBuildStatus

Data models

`BuildInfo`

@dataclass
class BuildInfo:
    build_id: str
    status: str
    template_id: str | None = None   # ID of the template being built
    logs: list[str] = []             # Build output; filled when build() returns

`TemplateBuildStatus`

@dataclass
class TemplateBuildStatus:
    build_id: str
    status: str             # "building", then "completed" or "failed"
    logs: list[str]         # Build output accumulated so far
    template_id: str | None = None

`CopyItem`

@dataclass
class CopyItem:
    src: str
    dst: str
    mode: int | None = None

AsyncTemplate

Use AsyncTemplate for async applications. It has the same static methods as Template but all are coroutines:

from declaw import AsyncTemplate, TemplateBase

template = TemplateBase().from_base_image("node:24")  # Node.js 24 LTS with npm

build_info = await AsyncTemplate.build(
    template=template,
    alias="node-env",
    api_key="your-api-key",
    domain="api.declaw.ai",
)

Methods: await AsyncTemplate.build(...), await AsyncTemplate.build_in_background(...), await AsyncTemplate.rebuild(...), await AsyncTemplate.rebuild_in_background(...), await AsyncTemplate.get_build_status(...).

Using a template in Sandbox.create()

Once a template is built successfully, reference it by alias:

from declaw import Sandbox

sbx = Sandbox.create(
    template="data-analysis",   # alias set during build
    api_key="your-api-key",
    domain="api.declaw.ai",
)
# pandas is already installed — no pip install needed
result = sbx.commands.run("python3 -c \"import pandas; print(pandas.__version__)\"")
print(result.stdout)
sbx.kill()

Python SDK

TypeScript SDK

Go SDK

TemplateBase

Methods

`.from_base_image(image)`

`.apt_install(*packages)`

`.run_cmd(cmds)`

`.copy(src, dst, mode)`

`.set_envs(envs)`

`.set_start_cmd(cmd, ready_check)`

`.to_dict()`

Template

`Template.build()`

`Template.build_in_background()`

`Template.rebuild()`

`Template.rebuild_in_background()`

`Template.get_build_status()`

Data models

`BuildInfo`

`TemplateBuildStatus`

`CopyItem`

AsyncTemplate

Using a template in Sandbox.create()

​TemplateBase

​Methods

​.from_base_image(image)

​.apt_install(*packages)

​.run_cmd(cmds)

​.copy(src, dst, mode)

​.set_envs(envs)

​.set_start_cmd(cmd, ready_check)

​.to_dict()

​Template

​Template.build()

​Template.build_in_background()

​Template.rebuild()

​Template.rebuild_in_background()

​Template.get_build_status()

​Data models

​BuildInfo

​TemplateBuildStatus

​CopyItem

​AsyncTemplate

​Using a template in Sandbox.create()

TemplateBase

Methods

`.from_base_image(image)`

`.apt_install(*packages)`

`.run_cmd(cmds)`

`.copy(src, dst, mode)`

`.set_envs(envs)`

`.set_start_cmd(cmd, ready_check)`

`.to_dict()`

Template

`Template.build()`

`Template.build_in_background()`

`Template.rebuild()`

`Template.rebuild_in_background()`

`Template.get_build_status()`

Data models

`BuildInfo`

`TemplateBuildStatus`

`CopyItem`

AsyncTemplate

Using a template in Sandbox.create()