Templates define the base filesystem image used when creating sandboxes. The default default template includes Python 3, Node.js, Go, and common utilities. Custom templates let you pre-install packages, copy in project files, and configure the environment once so every sandbox starts ready to run.
Default template
Unless you specify a template parameter, sandboxes use the default template which provides:
- Python 3 with pip
- Node.js with npm
- Go toolchain
- Common shell utilities (curl, wget, git, tar, jq)
Build a custom template
from declaw import Template
template = Template.build(
template="""
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip3 install numpy pandas scikit-learn matplotlib
WORKDIR /workspace
""",
alias="data-science",
)
print(template.template_id) # tpl-abc123
import { Template } from '@declaw/sdk';
const template = await Template.build({
template: `
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip3 install numpy pandas scikit-learn matplotlib
WORKDIR /workspace
`,
alias: 'data-science',
});
console.log(template.templateId);
Build with options
template = Template.build(
template="""
FROM ubuntu:22.04
RUN pip3 install anthropic openai langchain
COPY ./prompts /workspace/prompts
""",
alias="llm-agent",
cpu_count=2,
memory_mb=1024,
on_build_logs=lambda line: print(line), # stream build output
)
const template = await Template.build({
template: `
FROM ubuntu:22.04
RUN pip3 install anthropic openai langchain
`,
alias: 'llm-agent',
cpuCount: 2,
memoryMb: 1024,
onBuildLogs: (line) => console.log(line),
});
TemplateBase model
TemplateBase describes a template configuration before it is built.
| Field | Type | Description |
|---|
template | str | Dockerfile content for the template image |
alias | str | None | Human-readable name for the template |
cpu_count | int | Default vCPUs for sandboxes from this template (1–8) |
memory_mb | int | Default RAM for sandboxes from this template (128–8192) |
copy_files | list[CopyItem] | Files to copy into the template at build time |
Copy files into a template
Use CopyItem to embed files from the host into the template image at build time.
from declaw import Template, CopyItem
template = Template.build(
template="""
FROM ubuntu:22.04
RUN pip3 install -r /workspace/requirements.txt
""",
copy_files=[
CopyItem(
source_path="./requirements.txt",
dest_path="/workspace/requirements.txt",
),
CopyItem(
source_path="./scripts/",
dest_path="/workspace/scripts/",
),
],
alias="my-project",
)
CopyItem model
| Field | Type | Description |
|---|
source_path | str | Path on the host machine |
dest_path | str | Destination path inside the template image |
Start background build
Use build_in_background() to start a build without waiting, then poll the status.
build_id = Template.build_in_background(
template="""
FROM ubuntu:22.04
RUN apt-get install -y heavy-dependency
""",
alias="slow-build",
)
print(f"Build started: {build_id}")
Check build status
from declaw import TemplateBuildStatus
import time
while True:
status = Template.get_build_status(build_id)
print(status.status, status.progress)
if status.status == TemplateBuildStatus.done:
print(f"Template ready: {status.template_id}")
break
elif status.status == TemplateBuildStatus.error:
print(f"Build failed: {status.error}")
break
time.sleep(2)
BuildInfo model
| Field | Type | Description |
|---|
build_id | str | Unique build identifier |
template_id | str | None | Set once build completes successfully |
status | TemplateBuildStatus | pending, building, done, or error |
progress | float | Build progress 0.0–1.0 |
error | str | None | Error message if status is error |
logs | list[str] | Build log lines streamed during build |
TemplateBuildStatus enum
| Value | Description |
|---|
pending | Build queued, not yet started |
building | Build is in progress |
done | Build succeeded — template_id is set |
error | Build failed — error contains the reason |
Use a custom template
from declaw import Sandbox
sbx = Sandbox.create(template="data-science")
result = sbx.commands.run("python3 -c 'import pandas; print(pandas.__version__)'")
print(result.stdout) # 2.1.0
sbx = Sandbox.create(template="tpl-abc123")
Async template operations
from declaw import AsyncTemplate
template = await AsyncTemplate.build(
template="""
FROM ubuntu:22.04
RUN pip3 install torch transformers
""",
alias="ml-inference",
)
Template builds run on the server. Build time depends on the packages being installed and typically takes 1–5 minutes. Use build_in_background() for large builds to avoid blocking your process.
