Skip to main content
Every workspace runs on a base image - a pre-built Debian 12 root filesystem with tools and runtimes already installed. Templates combine an image with default resource settings (RAM, vCPU, disk) so you can deploy in one call.

​
Images

Images determine what software is available inside your workspace out of the box. All images include SSH access, systemd, and the Rigbox CLI.
Both images are built on Debian 12 (Bookworm) and include Python 3.12 and Node.js 22. Specialized software — VS Code, Jupyter, Architecture Explorer, Virtual Browser, and more — is layered on top of a workspace as app recipes and tools, not baked into a dedicated image.

​
What’s in each image

base is the right choice for most workloads. It includes:
  • Python 3.12 with uv for fast package management
  • Node.js 22 with npm
  • git, vim, tmux, curl, wget, jq
  • GitHub CLI (gh)
  • Pre-warmed npm caches for popular tools (Jupyter, Marimo, Streamlit, Excalidraw)
dev adds build tooling on top of base:
  • Docker CLI (for building images - Docker daemon runs on the host)
  • cmake, make, gcc, g++
  • strace, gdb, ltrace for debugging
  • PostgreSQL client (psql)

​
Listing Available Images

Images are not exposed as a standalone resource. The set of images you can boot is implied by the templates the server publishes — every template’s image field names the base image it uses. To see which images are currently available, list templates and read the image column:
To extract just the unique image names, filter the structured output with --query:
See List Templates for the full response schema.

​
Templates

Templates are pre-configured workspace definitions that pair an image with sensible resource defaults. Use them with quick deploy for one-call workspace creation. Requests below a template’s RAM, vCPU, or disk floor are raised before the workspace is created or started.

​
Listing Available Templates

See List Templates for the full response schema.

​
Choosing the Right Image

Use this decision tree to pick the image that fits your workload:

​
Do you need Architecture Explorer or Virtual Browser?

Spawn a dev workspace and install the tool you need with rig tools install — see Architecture Explorer and Virtual Browser.

​
Do you need Docker, cmake, or native build tools?

If you’re compiling C/C++ code, building Docker images, or need debugging tools like strace and gdb, use the dev image.

​
For everything else, use base

The base image covers Python, Node.js, and general development. It’s the smallest and fastest to boot.
You can always install additional packages inside any workspace with apt-get. The image choice just determines what’s pre-installed for faster startup.

​
Quick Deploy with a Template

The fastest way to create a workspace is rig workspace spawn with a template ID:
rig workspace spawn creates the workspace, boots it, and waits until it’s ready - all in one call. See Quick Deploy for the API form.

​
Custom Workspace with a Specific Template

If the template defaults don’t fit your needs, create a workspace manually and specify the template along with custom resource settings.
See Create Workspace for the API form.

​
Resizing After Creation

You can change the RAM, vCPU, and disk size of an existing workspace without switching images. The workspace must be stopped first.
You cannot change the template of an existing workspace. To switch templates, create a new workspace with --template set to the one you want.
See Update Workspace Resources for details.

​
Pre-warmed Caches

The base image includes pre-warmed npm caches for several popular tools. This means installing catalog apps like Jupyter, Marimo, Streamlit, and Excalidraw is significantly faster because dependencies are already downloaded. See Catalog Apps for how to install these tools.

​
Next Steps