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.

​
Before you begin

Use the v0.13 CLI and authenticate. Run workspace-management and recipe commands from your local terminal. Commands identified as running inside a workspace require its console terminal or SSH session. Replace example resource IDs with the values returned for your account.

​
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)
  • Package caches where included in the selected image revision
dev adds build tooling on top of base:
  • Docker tooling where provided by the selected image; use the supported build workflow instead of assuming access to a shared host daemon
  • cmake, make, gcc, g++
  • strace, gdb, ltrace for debugging
  • PostgreSQL client (psql)

​
Listing Available Images

List the server’s available templates and their readiness before selecting a starting environment. The legacy template commands remain callable in v0.13 but are hidden from general help:
To extract template identifiers, filter the structured output with --query. The CLI summary does not expose an image field:
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 is the starting point for Python, Node.js, and general development.
You can install additional packages with apt-get when the image provides it and your workspace has network access, permissions, and sufficient disk space. 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

Some image revisions include package caches. Cache presence, network access, and selected dependency versions affect installation time; do not depend on a fixed install duration. See Catalog Apps for how to install these tools.

​
Verify and troubleshoot

Inspect rig workspace ls and rig workspace services --workspace WORKSPACE_ID. For installed apps, check their status and health before opening the returned URL. A created resource or running VM does not by itself prove the application is ready. For failures, start with runtime logs, health checks, or resource exhaustion.

​
Next Steps