Templates

[breardon2011]

Templates System

Replaces the old Dockerfile-based template system with a new declarative, code-first templates system built on checkpointing. Supports two workflows:

On-demand Images

Define images programmatically with a fluent builder API. The server builds on first use, caches by content hash, and reuses instantly on subsequent creates.

const image = Image.base()
  .aptInstall(['curl', 'jq'])
  .pipInstall(['pandas'])
  .env({ APP_ENV: 'production' })
  .workdir('/workspace')

const sandbox = await Sandbox.create({ image })

Pre-built Snapshots

Build an image once, save it as a named snapshot. Snapshots persist permanently and create sandboxes instantly with no build step.

const snapshots = new Snapshots()
await snapshots.create({ name: 'data-science', image })
const sandbox = await Sandbox.create({ snapshot: 'data-science' })

What's included

Image Builder API

• Image.base() starts from the default OpenSandbox environment
• .aptInstall() / .pipInstall() — package management
• .runCommands() — arbitrary shell commands
• .env() / .workdir() — environment configuration
• .addFile() / .addLocalFile() / .addLocalDir() — embed files into the image
• Immutable & deterministic — same manifest always produces the same cache key

Snapshots CRUD

• create, list, get, delete via SDK and dashboard

Build Log Streaming

• SSE-based real-time build log callbacks (onBuildLog / onBuildLogs)
• Cache hits emit a "found in cache" message

Server

• Image manifest resolution with content-hash caching
• Dedicated SSE handlers for sandbox and snapshot creation
• Dashboard API endpoints for listing/deleting cached images

Dashboard

• New Templates page (/templates) showing declarative image snapshots
• Displays build steps summary, status, linked checkpoints, last used date

Documentation

• Full Templates docs for both TypeScript and Python SDKs
• Covers both workflows, complete Image API reference, and end-to-end examples

Old Template System Removed

• Removed Dockerfile-based buildTemplate / saveAsTemplate API routes and handlers
• Removed Templates class from both SDKs
• Removed "Save as Template" UI from session detail page
• Stubbed old gRPC handlers (BuildTemplate, SaveAsTemplate) as unimplemented

Test Coverage

• TypeScript: 33 integration tests (all passing)
• Python: 29 integration tests (all passing)

SDK Parity

• Full feature parity between TypeScript (@opencomputer/sdk) and Python (opencomputer)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
opensandbox	Ready	Preview, Comment	Mar 10, 2026 4:40pm