Templates

A template is the rootfs image used when a sandbox boots. Declaw ships a small set of curated built-in templates for the most common workloads, and you can build your own when you need a different runtime, custom packages, or project files baked in. If you don’t pass template, sandboxes use base — a minimal Ubuntu 22.04 image with shell utilities only.

Built-in templates

Template	What’s preinstalled	Use it for
`base`	`Ubuntu 22.04`, `git`, `curl`, `wget`, `jq`, `build-essential`	Shell-only workflows, custom toolchains
`python`	`base` + `Python 3.10`, `pip`, `numpy`, `pandas`, `requests`, `httpx`, `pydantic`	Python scripts, data processing, REST clients
`node`	`base` + `Node.js 20 LTS`, `npm`, `typescript`, `yarn`	TypeScript / Node scripts, npm packages
`ai-agent`	`base` + `Python 3.10` + `Node.js 20` + LLM/agent SDKs (full list)	Agent workloads — LangChain, CrewAI, AutoGen, LlamaIndex, MCP

Built-in templates are versioned with the platform — you don’t need to build them. They are referenced by name (template="python", etc.) and pull a pre-published rootfs image from the Declaw blob store.

How to choose

Need to run a one-off shell command or your own statically-linked binary? → base
Running Python code, especially with requests / pandas / numpy? → python
Running a TypeScript or Node.js script? → node
Running an LLM-driven agent (LangChain, CrewAI, AutoGen, LlamaIndex, OpenAI Agents, MCP)? → ai-agent

If your workload needs something not in the list above (a different language runtime, a heavy ML framework like torch, project files baked in, etc.) — build a custom template. See Build a custom template below.

Worked examples

Each built-in template has a runnable cookbook example you can copy:

base — shell tools

Run git, curl, and jq end-to-end inside a fresh sandbox.

python — pandas analysis

Pipe a CSV through pandas and read back JSON results.

node — TypeScript script

Compile a .ts file with tsc and run the output with Node.js 20.

ai-agent — frameworks check

Boot an agent sandbox and verify the major LLM-framework SDKs import.

ai-agent — KYC with CrewAI

Fintech: four-agent CrewAI KYC pipeline with PII + injection defense.

ai-agent — prior auth with LangGraph

Health-tech: LangGraph workflow with PHI redact + rehydrate around GPT-4.1.

Build a custom template

Use Template.build() when none of the built-ins fit — most commonly when you need extra system or Python packages, or a different base image. Describe the image with TemplateBase, using its helpers or a Dockerfile, and give the template an alias: sandboxes are created from it by that name. build() waits for the build to finish, which usually takes several minutes.

Python
TypeScript

from declaw import Template, TemplateBase

template = (
    TemplateBase()
    .from_base_image("ubuntu:22.04")
    .apt_install("python3", "python3-pip")
    .run_cmd(["pip3 install numpy pandas scikit-learn matplotlib"])
)
build = Template.build(template, alias="data-science")
print(build.template_id)  # tpl-3f9c2a1b7d4e8f60

import { Template, TemplateBase } from '@declaw/sdk';

const template = new TemplateBase()
  .fromBaseImage('ubuntu:22.04')
  .aptInstall('python3', 'python3-pip')
  .runCmd(['pip3 install numpy pandas scikit-learn matplotlib']);

const build = await Template.build(template, 'data-science');
console.log(build.templateId);

Build from a Dockerfile, with options

Python
TypeScript

template = TemplateBase().from_dockerfile("""
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip3 install anthropic openai langchain
""")
Template.build(
    template,
    alias="llm-agent",
    cpu_count=2,
    memory_mb=1024,
    on_build_logs=print,  # streams build output while waiting
)

const template = new TemplateBase().fromDockerfile(`
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip3 install anthropic openai langchain
`);
await Template.build(template, 'llm-agent', {
  cpuCount: 2,
  memoryMb: 1024,
  onBuildLogs: (line) => console.log(line),
});

A Dockerfile build keeps only the files the Dockerfile produces. Its ENV, WORKDIR and CMD are not applied to sandboxes, and in Python and TypeScript the builder methods (set_envs(), apt_install(), run_cmd(), …) are ignored on a Dockerfile template. Pass environment variables when you create the sandbox (envs), and give commands a working directory with cwd.

Build options

Option	Description
`alias`	Required. The template’s name, unique within your account. Lowercase letters, digits and hyphens, 1-128 chars, starting with a letter or digit. Built-in names (`base`, `python`, `node`, …) are reserved.
`cpu_count` / `cpuCount`	Default vCPUs for sandboxes from this template (1–8)
`memory_mb` / `memoryMb`	Default RAM for sandboxes from this template (128–8192)
`disk_mb` / `diskMb`	Disk size in MB: 512, 2048, 4096, 8192 or 16384 (default 4096). Other sizes round up to the next one. Your plan caps it: free 8192, pro and enterprise 16384.
`on_build_logs` / `onBuildLogs`	Called with each new line of build output while `build()` waits
`build_timeout` / `buildTimeout`	How long `build()` waits: one hour by default (seconds in Python, milliseconds in TypeScript). The build keeps running if the wait ends first.

Copying local files

TemplateBase.copy() is not supported yet. A template build cannot upload local files, so building a template that uses copy() raises InvalidArgumentError. Download files in a run_cmd step (for example curl -fsSL -o /workspace/app.py https://...), or bake them into a Dockerfile.

Start a background build

Use build_in_background() to start a build without waiting, then poll its status.

Python

info = Template.build_in_background(template, alias="slow-build")
print(f"Build started: {info.build_id}")

Check build status

Python

import time

while True:
    status = Template.get_build_status(info.build_id)
    if status.status == "completed":
        print(f"Template ready: {status.template_id}")
        break
    if status.status == "failed":
        print("Build failed:\n" + "\n".join(status.logs[-20:]))
        break
    time.sleep(3)

BuildInfo model

Field	Type	Description
`build_id`	`str`	Unique build identifier
`template_id`	`str \| None`	ID of the template being built
`status`	`str`	`building`, then `completed` or `failed`
`logs`	`list[str]`	Build output. Empty for a build that has just started; `build()` returns the full output

Build status values

Value	Description
`building`	Build is in progress
`completed`	Build succeeded — sandboxes can be created from the template’s alias
`failed`	Build failed — `logs` holds the output; `build()` raises `BuildError`

Template lifecycle

A custom template is immutable once built. The lifecycle is:

create ──▶ building ──▶ ready ──▶ delete
             │  ▲
             ▼  │ rebuild
           failed

Ready templates cannot be changed. To alter a template’s contents, delete it and create a new one. Rebuilding a live template would replace its image while workers already running it kept serving the old one, so the API refuses it with 409 template_immutable. A failed build is recoverable. POST /templates/{template_id}/rebuild re-runs the stored spec — it does not accept a new one. Use it when a build failed, or when a build was interrupted. Returns 202; poll GET /templates/builds/{build_id} for the result. A failed template keeps its alias, so building again under that alias returns 409: to build a changed spec under the same name, delete the failed template first (declaw template delete <template-id>). Sandboxes require a ready template. Creating a sandbox against a template that is still building or whose build failed returns 409 template_not_ready rather than starting a sandbox on a missing or half-written image. Built-in templates are always ready.

A build interrupted by a control-plane restart is marked failed automatically after a timeout, so it never stays stuck in building. Rebuild it once that happens.

Use a custom template

Create sandboxes from a custom template by its alias:

from declaw import Sandbox

sbx = Sandbox.create(template="data-science")
result = sbx.commands.run("python3 -c 'import pandas; print(pandas.__version__)'")
print(result.stdout)

The template ID (tpl-…) identifies the template in GET and DELETE /templates/{template_id}; sandbox creation does not accept it in place of the alias.

Async template operations

from declaw import AsyncTemplate, TemplateBase

template = TemplateBase().from_dockerfile("""
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y python3-pip
RUN pip3 install torch transformers
""")
build = await AsyncTemplate.build(template, alias="ml-inference")

Template builds run on the server and usually take several minutes, depending on what is installed. build() waits for the build to finish (up to build_timeout); use build_in_background() to return immediately and poll get_build_status() instead.

Getting Started

Core Features

CLI

Security

Platform

Deployment

Architecture

Built-in templates

How to choose

Worked examples

base — shell tools

python — pandas analysis

node — TypeScript script

ai-agent — frameworks check

ai-agent — KYC with CrewAI

ai-agent — prior auth with LangGraph

Build a custom template

Build from a Dockerfile, with options

Build options

Copying local files

Start a background build

Check build status

BuildInfo model

Build status values

Template lifecycle

Use a custom template

Async template operations

​Built-in templates

​How to choose

​Worked examples

base — shell tools

python — pandas analysis

node — TypeScript script

ai-agent — frameworks check

ai-agent — KYC with CrewAI

ai-agent — prior auth with LangGraph

​Build a custom template

​Build from a Dockerfile, with options

​Build options

​Copying local files

​Start a background build

​Check build status

​BuildInfo model

​Build status values

​Template lifecycle

​Use a custom template

​Async template operations

Built-in templates

How to choose

Worked examples

Build a custom template

Build from a Dockerfile, with options

Build options

Copying local files

Start a background build

Check build status

BuildInfo model

Build status values

Template lifecycle

Use a custom template

Async template operations