> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rigbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Images & Templates

> Choose the right base image and template for your workspace.

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.

| Image  | Size | Includes                                                                            | Best for                               |
| ------ | ---- | ----------------------------------------------------------------------------------- | -------------------------------------- |
| `base` | 3 GB | Python 3.12, Node.js 22, uv, git, vim, tmux, GitHub CLI                             | General development, scripts, web apps |
| `dev`  | 4 GB | Everything in base + Docker CLI, cmake, build tools, strace, gdb, PostgreSQL client | Systems programming, native builds     |

<Note>
  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](/guides/catalog) and [tools](/guides/architecture-explorer), not baked into a dedicated image.
</Note>

### 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:

```bash theme={null}
rig template ls
```

To extract just the unique image names, filter the structured output with `--query`:

```bash theme={null}
rig template ls --output json --query "templates[].image"
```

See [List Templates](/api-reference/templates/list) 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](/api-reference/templates/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.

| Template      | Image | RAM    | vCPU | Disk | Use case                                   |
| ------------- | ----- | ------ | ---- | ---- | ------------------------------------------ |
| `base`        | base  | 512 MB | 1    | 3 GB | Minimal workspace for scripts and web apps |
| `dev`         | dev   | 1 GB   | 1    | 4 GB | Developer environment with build tools     |
| `custom-repo` | base  | 1 GB   | 1    | 3 GB | Clone and run a git repository             |

### Listing Available Templates

```bash theme={null}
rig template ls
```

See [List Templates](/api-reference/templates/list) 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](/guides/architecture-explorer) and [Virtual Browser](/guides/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.

<Tip>
  You can always install additional packages inside any workspace with `apt-get`. The image choice just determines what's pre-installed for faster startup.
</Tip>

## Quick Deploy with a Template

The fastest way to create a workspace is `rig workspace spawn` with a template ID:

```bash theme={null}
rig workspace spawn --name my-project --template dev
```

`rig workspace spawn` creates the workspace, boots it, and waits until it's ready - all in one call. See [Quick Deploy](/api-reference/templates/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.

```bash theme={null}
rig workspace new --name heavy-compute --template dev --ram 2048 --vcpu 2 --disk 8192
```

See [Create Workspace](/api-reference/workspaces/create) 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.

```bash theme={null}
rig workspace stop --workspace my-project

rig workspace resize --workspace my-project --ram 2048 --vcpu 2

rig workspace start --workspace my-project
```

<Warning>
  You cannot change the template of an existing workspace. To switch templates, create a new workspace with `--template` set to the one you want.
</Warning>

See [Update Workspace Resources](/api-reference/workspaces/update-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.

| Tool        | Cache benefit                                 |
| ----------- | --------------------------------------------- |
| Jupyter Lab | npm packages cached, installs in \~30 seconds |
| Marimo      | npm packages cached, installs in \~20 seconds |
| Streamlit   | pip packages cached via uv                    |
| Excalidraw  | npm packages cached, installs in \~15 seconds |

See [Catalog Apps](/guides/catalog) for how to install these tools.

## Next Steps

* [Workspaces](/guides/workspaces) - create, start, stop, and manage workspace lifecycle
* [Expose Ports & Route Apps](/guides/expose-and-route) - make services accessible at `*.rigbox.dev`
* [Catalog Apps](/guides/catalog) - install VS Code, Jupyter, and more with one call