Templates

import { Template, TemplateBase } from '@declaw/sdk';
import type { BuildInfo, TemplateBuildStatus, CopyItem, TemplateBuildOpts, GetBuildStatusOpts } from '@declaw/sdk';

Templates let you pre-build sandbox images with specific packages, files, and environment variables. Once built, reference a template by alias in Sandbox.create({ template: 'my-alias' }).

TemplateBase

TemplateBase is a fluent class for defining template contents. Chain methods to build the definition, then pass it to Template.build().

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

const template = new TemplateBase()
  .fromBaseImage('ubuntu:22.04')
  .aptInstall('python3', 'python3-pip', 'nodejs', 'npm')
  .runCmd(['pip3', 'install', 'pandas', 'numpy'])
  .setEnvs({ PYTHONPATH: '/home/user', NODE_ENV: 'production' })
  .setStartCmd('sleep infinity');

`.fromBaseImage(image?)`

Set the base Docker image.

string

default:"'ubuntu:22.04'"

Docker image tag.

Returns this

`.aptInstall(...packages)`

Install apt packages.

template.aptInstall('git', 'curl', 'jq');

string[]

required

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

Returns this

`.runCmd(cmds)`

Add a build-time command (equivalent to a Dockerfile RUN).

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

string[]

required

Command as an array of strings (executable + arguments).

Returns this

`.copy(src, dst, mode?)`

Copy a local file into the image at build time.

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

string

required

Local path to the file.

string

required

Destination path inside the image.

number

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

Returns this

`.setEnvs(envs)`

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

template.setEnvs({ APP_ENV: 'production', PORT: '8080' });

Record<string, string>

required

Key-value pairs to set as environment variables.

Returns this

`.setStartCmd(cmd)`

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(cmd, { background: true }) after creating the sandbox.

template.setStartCmd('python3 /app/server.py');

string

required

Shell command to execute on sandbox start.

Returns this

`.toJSON()`

Serialize the template to a JSON-friendly object for the API. Returns Record<string, any>

Template

Template is a static class for submitting and querying template builds. All methods are async.

`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 onBuildLogs.

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

const template = new TemplateBase()
  .aptInstall('python3-pip')
  .runCmd(['pip3', 'install', 'pandas']);

const info: BuildInfo = await Template.build(template, 'data-analysis', {
  cpuCount: 2,
  memoryMb: 2048,
  onBuildLogs: (log) => console.log(log),
  apiKey: 'your-api-key',
  domain: 'api.declaw.ai',
});

console.log('Template ID:', info.templateId);

TemplateBase

required

The template definition to build.

string

required

Human-readable name used as template in Sandbox.create().

TemplateBuildOpts

Optional build options.

`TemplateBuildOpts`

number

Number of CPUs for the build worker.

number

Memory in MB for the build worker.

number

default:"4096"

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

(log: string) => void

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.

number

default:"3600000"

Milliseconds to wait for the build to finish. If it is still running, TimeoutError is thrown; the build keeps running, and getBuildStatus() follows it.

string

API key override.

string

Domain override.

number

Per-request HTTP timeout in milliseconds.

Returns Promise<BuildInfo> with status completed. Throws

BuildError — the build failed. The message quotes the end of the build output; .buildId and .logs hold the rest.
TimeoutError — the build was still running after buildTimeout.
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.buildInBackground()`

Submit a template build and return immediately without waiting.

const info = await Template.buildInBackground(template, 'my-template', {
  apiKey: 'your-api-key',
  domain: 'api.declaw.ai',
});
console.log('Build started:', info.buildId);

Parameters are the same as Template.build() except onBuildLogs and buildTimeout, which only apply while waiting. Returns Promise<BuildInfo> with status building.

`Template.rebuild()`

Needs @declaw/sdk 1.6.0 or later. Upgrade with npm install @declaw/sdk@latest.

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

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

try {
  await Template.build(template, 'my-template');
} catch (err) {
  if (err instanceof BuildError && err.templateId) {
    // The failed template keeps its alias; retry it by ID.
    const info = await Template.rebuild(err.templateId, { onBuildLogs: console.log });
    console.log(info.status); // 'completed'
  }
}

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: build() with the same alias is refused with a ConflictError whose message names the template to rebuild. Options (TemplateRebuildOpts) are onBuildLogs, buildTimeout, apiKey, domain and requestTimeout, as for build(); there are no resources to set. Returns Promise<BuildInfo> with status completed. Throws BuildError, ConflictError, TimeoutError.

`Template.rebuildInBackground()`

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

const info = await Template.rebuildInBackground('tpl-1234567890abcdef');
console.log('Rebuild started:', info.buildId);

Returns Promise<BuildInfo> with status building.

`Template.getBuildStatus()`

Poll the status of a background build.

const status = await Template.getBuildStatus('build-id', {
  apiKey: 'your-api-key',
  domain: 'api.declaw.ai',
});
console.log(status.status);       // "building" | "completed" | "failed"
console.log(status.logs.at(-1));  // latest log line

string

required

Build ID from a previous build() or buildInBackground() call. Must be alphanumeric with hyphens/underscores.

GetBuildStatusOpts

Optional: apiKey, domain, requestTimeout.

Returns Promise<TemplateBuildStatus>

Data models

`BuildInfo`

interface BuildInfo {
  buildId: string;
  status: string;
  templateId?: string;  // ID of the template being built
  logs: string[];       // Build output; filled when build() resolves
}

`TemplateBuildStatus`

interface TemplateBuildStatus {
  buildId: string;
  status: string;      // "building" | "completed" | "failed"
  logs: string[];      // Build output accumulated so far
  templateId?: string;
}

`CopyItem`

interface CopyItem {
  src: string;
  dst: string;
  mode?: number;
}

`GetBuildStatusOpts`

interface GetBuildStatusOpts {
  apiKey?: string;
  domain?: string;
  requestTimeout?: number;
}

Polling a background build

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

const template = new TemplateBase()
  .fromBaseImage('node:24') // Node.js 24 LTS with npm
  .runCmd(['npm', 'install', '-g', 'typescript']);

const info = await Template.buildInBackground(template, 'node-ts', {
  apiKey: 'your-api-key',
  domain: 'api.declaw.ai',
});

let status = await Template.getBuildStatus(info.buildId, {
  apiKey: 'your-api-key',
  domain: 'api.declaw.ai',
});

while (status.status === 'building') {
  await new Promise((r) => setTimeout(r, 3000));
  status = await Template.getBuildStatus(info.buildId, {
    apiKey: 'your-api-key',
    domain: 'api.declaw.ai',
  });
  console.log(`Build ${status.status}: ${status.logs.at(-1) ?? ''}`);
}

if (status.status !== 'completed') {
  throw new Error('Template build failed');
}

Using a template

import { Sandbox } from '@declaw/sdk';

const sbx = await Sandbox.create({
  template: 'data-analysis',  // alias set during build
  apiKey: 'your-api-key',
  domain: 'api.declaw.ai',
});

// pandas is already installed
const result = await sbx.commands.run(
  'python3 -c "import pandas; print(pandas.__version__)"',
);
console.log(result.stdout);
await sbx.kill();

Python SDK

TypeScript SDK

Go SDK

TemplateBase

`.fromBaseImage(image?)`

`.aptInstall(...packages)`

`.runCmd(cmds)`

`.copy(src, dst, mode?)`

`.setEnvs(envs)`

`.setStartCmd(cmd)`

`.toJSON()`

Template

`Template.build()`

`TemplateBuildOpts`

`Template.buildInBackground()`

`Template.rebuild()`

`Template.rebuildInBackground()`

`Template.getBuildStatus()`

Data models

`BuildInfo`

`TemplateBuildStatus`

`CopyItem`

`GetBuildStatusOpts`

Polling a background build

Using a template

​TemplateBase

​.fromBaseImage(image?)

​.aptInstall(...packages)

​.runCmd(cmds)

​.copy(src, dst, mode?)

​.setEnvs(envs)

​.setStartCmd(cmd)

​.toJSON()

​Template

​Template.build()

​TemplateBuildOpts

​Template.buildInBackground()

​Template.rebuild()

​Template.rebuildInBackground()

​Template.getBuildStatus()

​Data models

​BuildInfo

​TemplateBuildStatus

​CopyItem

​GetBuildStatusOpts

​Polling a background build

​Using a template

TemplateBase

`.fromBaseImage(image?)`

`.aptInstall(...packages)`

`.runCmd(cmds)`

`.copy(src, dst, mode?)`

`.setEnvs(envs)`

`.setStartCmd(cmd)`

`.toJSON()`

Template

`Template.build()`

`TemplateBuildOpts`

`Template.buildInBackground()`

`Template.rebuild()`

`Template.rebuildInBackground()`

`Template.getBuildStatus()`

Data models

`BuildInfo`

`TemplateBuildStatus`

`CopyItem`

`GetBuildStatusOpts`

Polling a background build

Using a template