Images

Every workspace starts from a base image - a pre-configured environment with an operating system and optional software. You can install packages, write files, and make any changes - they persist across restarts until the workspace is deleted.

How images work

Changes you make persist across restarts
You can snapshot your workspace at any time
The base image provides the starting environment; your changes are additive

Choosing an image

Start with the runtime

If you know what language you're running, pick the runtime image directly:

// Node.js project
await ws.create({ image: 'node-20' });

// Python project
await ws.create({ image: 'python-3.12' });

// Go project
await ws.create({ image: 'go-1.22' });

Runtime images include the language, package manager, and common build tools on top of Ubuntu.

Start with the OS

If you need a clean slate or will install custom software:

// Minimal Ubuntu
await ws.create({ image: 'ubuntu-24' });

// Ultra-lightweight Alpine
await ws.create({ image: 'alpine-3' });

Need a database?

Database images come pre-configured and ready to accept connections:

await ws.create({ image: 'postgres-16' });
await ws.create({ image: 'redis-7' });

Image catalog

Category	Image ID	Based on	Includes
OS	`ubuntu-22`	Ubuntu 22.04 LTS	curl, wget, git, vim, build-essential
OS	`ubuntu-24`	Ubuntu 24.04 LTS	curl, wget, git, vim, build-essential
OS	`debian-12`	Debian 12	curl, wget, git, vim
OS	`alpine-3`	Alpine 3	busybox, apk
Runtime	`node-20`	Ubuntu + Node.js 20 LTS	node, npm, npx, yarn
Runtime	`node-22`	Ubuntu + Node.js 22	node, npm, npx, yarn
Runtime	`python-3.12`	Ubuntu + Python 3.12	python3, pip, venv
Runtime	`python-3.13`	Ubuntu + Python 3.13	python3, pip, venv
Runtime	`go-1.22`	Ubuntu + Go 1.22	go, gofmt
Runtime	`rust-1`	Ubuntu + Rust stable	rustc, cargo, rustup
Database	`redis-7`	Ubuntu + Redis 7	redis-server, redis-cli
Database	`postgres-16`	Ubuntu + PostgreSQL 16	pg, psql, pg_dump

Installing additional software

Every image supports package installation at runtime:

// Install packages after creation
await ws.exec(workspaceId, {
  cmd: ['apt-get', 'update', '&&', 'apt-get', 'install', '-y', 'ffmpeg'],
});

Or set a startup command:

await ws.create({
  image: 'ubuntu-24',
  config: {
    cmd: ['bash', '-c', 'apt-get update && apt-get install -y ffmpeg && sleep infinity'],
  },
});

Software installed at runtime persists across restarts but is lost when the workspace is deleted. Use snapshots to preserve complex setups.

Tips

Use runtime images when possible - they save setup time
Alpine is the smallest image (~5 MB) but uses musl libc, which may cause compatibility issues with some binaries
Database images auto-start the database service - no manual setup needed
Browse images programmatically via the Images API

On this page