Templates - OpenComputer

Templates provide a code-first approach to defining sandbox environments. Instead of configuring images manually, you define them programmatically using the SDK. The system supports two workflows:

Declarative images — build images with varying dependencies on demand when creating sandboxes
Pre-built snapshots — create and register ready-to-use snapshots that can be shared across multiple sandboxes

Declarative image building

Build images on-the-fly when creating sandboxes. Ideal for iterating quickly without creating separate snapshots. Declarative images are cached by content hash — identical manifests produce the same image. Subsequent runs reuse the cached image instantly.

import { Sandbox, Image } from '@opencomputer/sdk';

// Define an image with packages, env vars, and files
const image = Image.base()
  .aptInstall(['curl', 'jq'])
  .pipInstall(['requests', 'pandas'])
  .env({ PROJECT_ROOT: '/workspace' })
  .workdir('/workspace');

// Create a sandbox — the image is built on first run, cached after
const sandbox = await Sandbox.create({
  image,
  timeout: 300,
  onBuildLog: (log) => console.log(`build: ${log}`),
});

const result = await sandbox.commands.run('which curl');
console.log(result.exitCode); // 0

`Sandbox.create({ image, onBuildLog? })`

When you pass an image to Sandbox.create(), the server:

Hashes the image manifest to compute a cache key
If cached, creates the sandbox from the existing checkpoint instantly
If not cached, boots a build sandbox, executes each step, checkpoints the result, then creates your sandbox from it

image

Image

A declarative image definition built with the Image builder.

onBuildLog

(log: string) => void

Callback for streaming build log messages via SSE. Receives step-by-step progress updates during image building.

Creating pre-built snapshots

Create named snapshots that persist permanently and can be shared across sandboxes. Snapshots are visible in the dashboard and don’t need to be rebuilt.

import { Image, Snapshots } from '@opencomputer/sdk';

const snapshots = new Snapshots();

// Define the image
const image = Image.base()
  .aptInstall(['python3-pip'])
  .pipInstall(['pandas', 'numpy', 'scikit-learn'])
  .workdir('/workspace');

// Create a named snapshot with build log streaming
await snapshots.create({
  name: 'data-science',
  image,
  onBuildLogs: (log) => console.log(`build: ${log}`),
});

// Now create sandboxes from the snapshot — instant, no build step
const sandbox = await Sandbox.create({ snapshot: 'data-science' });

`new Snapshots(opts?)`

opts

SnapshotOpts

Show properties

apiKey

string

API key. Falls back to OPENCOMPUTER_API_KEY env var.

apiUrl

string

API base URL. Falls back to OPENCOMPUTER_API_URL env var.

`snapshots.create(opts)`

Creates a pre-built snapshot from a declarative image.

opts

CreateSnapshotOpts

required

Show properties

name

string

required

Unique name for this snapshot.

image

Image

required

Declarative image definition.

onBuildLogs

(log: string) => void

Callback for streaming build log messages.

Returns: Promise<SnapshotInfo>

`snapshots.list()`

Returns all named snapshots for the current organization.

const list = await snapshots.list();
for (const s of list) {
  console.log(`${s.name} — ${s.status}`);
}

Returns: Promise<SnapshotInfo[]>

`snapshots.get(name)`

Gets a snapshot by name.

const snapshot = await snapshots.get('data-science');
console.log(snapshot.status); // "ready"

name

string

required

Snapshot name.

Returns: Promise<SnapshotInfo>

`snapshots.delete(name)`

Deletes a named snapshot. Existing sandboxes created from it are not affected.

await snapshots.delete('data-science');

name

string

required

Snapshot name to delete.

Returns: Promise<void>

`Sandbox.create({ snapshot })`

Create a sandbox from a pre-built snapshot by name.

const sandbox = await Sandbox.create({ snapshot: 'data-science' });

snapshot

string

Name of a pre-built snapshot to create the sandbox from.

Returns: Promise<Sandbox>

Image configuration

The Image class provides a fluent, immutable API for defining sandbox environments. Each method returns a new Image instance — the original is never modified.

`Image.base()`

Creates a new image starting from the default OpenSandbox environment (Ubuntu 22.04 with Python, Node.js, build tools, and common utilities).

const image = Image.base();

`image.aptInstall(packages)`

Install system packages via apt-get.

const image = Image.base().aptInstall(['curl', 'git', 'jq']);

packages

string[]

required

List of apt package names to install.

`image.pipInstall(packages)`

Install Python packages via pip.

const image = Image.base().pipInstall(['requests', 'pandas', 'numpy']);

packages

string[]

required

List of pip package names to install.

`image.runCommands(...commands)`

Run one or more shell commands during image build.

const image = Image.base().runCommands(
  'mkdir -p /workspace/project',
  'echo "Hello" > /workspace/welcome.txt',
);

commands

string[]

required

Shell commands to execute sequentially.

`image.env(vars)`

Set environment variables. Written to /etc/environment so they’re available in all sessions.

const image = Image.base().env({
  PROJECT_ROOT: '/workspace',
  NODE_ENV: 'production',
});

vars

Record<string, string>

required

Key-value pairs of environment variables.

`image.workdir(path)`

Set the default working directory.

const image = Image.base().workdir('/workspace/project');

path

string

required

Absolute path for the working directory.

`image.addFile(remotePath, content)`

Embed a file with inline content into the image.

const image = Image.base()
  .addFile('/workspace/config.json', '{"env": "production"}')
  .addFile('/workspace/setup.sh', '#!/bin/bash\necho "Ready!"');

remotePath

string

required

Absolute path inside the sandbox.

content

string

required

String content of the file.

`image.addLocalFile(localPath, remotePath)`

Read a file from the local machine and embed it into the image.

const image = Image.base()
  .addLocalFile('package.json', '/workspace/package.json');

localPath

string

required

Path to the file on the local machine.

remotePath

string

required

Absolute path inside the sandbox.

`image.addLocalDir(localPath, remotePath)`

Recursively read a local directory and embed all files into the image.

const image = Image.base()
  .addLocalDir('src', '/workspace/src');

localPath

string

required

Path to the directory on the local machine.

remotePath

string

required

Absolute path inside the sandbox where the directory will be created.

`image.toJSON()`

Returns the image manifest as a plain object. Returns: ImageManifest

`image.cacheKey()`

Computes a deterministic SHA-256 hash of the manifest for cache lookups. Returns: string

SnapshotInfo

Field	Type	Description
`id`	`string`	Unique snapshot identifier
`name`	`string`	Snapshot name
`status`	`string`	`"building"`, `"ready"`, or `"failed"`
`contentHash`	`string`	SHA-256 hash of the image manifest
`checkpointId`	`string`	Linked checkpoint ID
`manifest`	`object`	The declarative image manifest
`createdAt`	`string`	ISO 8601 creation timestamp
`lastUsedAt`	`string`	ISO 8601 last usage timestamp

Complete example

import { Sandbox, Image, Snapshots } from '@opencomputer/sdk';

// ── Pattern 1: On-demand image ──
const devImage = Image.base()
  .aptInstall(['curl', 'jq'])
  .pipInstall(['requests'])
  .addFile('/workspace/config.json', '{"debug": true}')
  .env({ APP_ENV: 'development' })
  .workdir('/workspace');

const sandbox = await Sandbox.create({
  image: devImage,
  onBuildLog: console.log,
});

await sandbox.commands.run('curl --version');
await sandbox.kill();

// ── Pattern 2: Pre-built snapshot ──
const snapshots = new Snapshots();

const prodImage = Image.base()
  .aptInstall(['python3-pip', 'git'])
  .pipInstall(['pandas', 'numpy', 'scikit-learn'])
  .runCommands('mkdir -p /workspace/data')
  .env({ APP_ENV: 'production' })
  .workdir('/workspace');

await snapshots.create({
  name: 'ml-env',
  image: prodImage,
  onBuildLogs: console.log,
});

// Instant — no build, just boot from snapshot
const mlSandbox = await Sandbox.create({ snapshot: 'ml-env' });
await mlSandbox.commands.run('python3 -c "import pandas; print(pandas.__version__)"');
await mlSandbox.kill();

// Cleanup
await snapshots.delete('ml-env');

TypeScript SDK

​Declarative image building

​Sandbox.create({ image, onBuildLog? })

​Creating pre-built snapshots

​new Snapshots(opts?)

​snapshots.create(opts)

​snapshots.list()

​snapshots.get(name)

​snapshots.delete(name)

​Sandbox.create({ snapshot })

​Image configuration

​Image.base()

​image.aptInstall(packages)

​image.pipInstall(packages)

​image.runCommands(...commands)

​image.env(vars)

​image.workdir(path)

​image.addFile(remotePath, content)

​image.addLocalFile(localPath, remotePath)

​image.addLocalDir(localPath, remotePath)

​image.toJSON()

​image.cacheKey()

​SnapshotInfo

​Complete example

Declarative image building

`Sandbox.create({ image, onBuildLog? })`

Creating pre-built snapshots

`new Snapshots(opts?)`

`snapshots.create(opts)`

`snapshots.list()`

`snapshots.get(name)`

`snapshots.delete(name)`

`Sandbox.create({ snapshot })`

Image configuration

`Image.base()`

`image.aptInstall(packages)`

`image.pipInstall(packages)`

`image.runCommands(...commands)`

`image.env(vars)`

`image.workdir(path)`

`image.addFile(remotePath, content)`

`image.addLocalFile(localPath, remotePath)`

`image.addLocalDir(localPath, remotePath)`

`image.toJSON()`

`image.cacheKey()`

SnapshotInfo

Complete example