Images

Every workspace starts from a base image — a pre-configured environment with an operating system and optional software. The catalog includes OS images, language runtimes, databases, AI agents, frameworks, dev tools, and more. New images are added regularly.

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-22' });

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

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

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:

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

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

Need a database, agent, or framework?

Images span many categories beyond just runtimes:

// Database
await ws.create({ image: 'postgres' });

// AI coding agent
await ws.create({ image: 'claude-code' });

// Workflow automation
await ws.create({ image: 'n8n' });

// Browser automation
await ws.create({ image: 'browserless' });

Image categories

The catalog is organized by category. Use the API to browse all images or filter by category:

// List all images
const all = await ws.images.list();

// Filter by category
const agents = await ws.images.list({ category: 'agent' });
const runtimes = await ws.images.list({ category: 'runtime' });
const databases = await ws.images.list({ category: 'database' });

Installing additional software

Every image supports package installation at runtime:

// Install packages after creation via Runtime
const rt = await ws.runtime(workspaceId);
await rt.exec.run(['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'],
  },
});

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