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

# Runtimes

> Configure where and how Xum executes agent workspaces

Runtimes determine where and how Xum executes agent workspaces. A runtime is two independent choices that compose:

* **Project isolation** — where the project lives and commands run.
* **Workspace isolation** — how each workspace is separated from the other workspaces of the project.

| Project isolation | Runs on |
| - | - |
| **Local** | This machine |
| **[SSH](https://xum.cdr.dev/runtime/ssh.md)** | A remote host over SSH |
| **[Coder](https://xum.cdr.dev/runtime/coder.md)** | A Coder workspace, reached over SSH |

| Workspace isolation | Each workspace gets | Best For |
| - | - | - |
| **[None](https://xum.cdr.dev/runtime/local.md)** | The shared project directory | Quick edits to your working copy |
| **[Worktree](https://xum.cdr.dev/runtime/worktree.md)** | Its own git worktree | Running multiple agents in parallel |
| **[Docker](https://xum.cdr.dev/runtime/docker.md)** | Its own container | Full isolation, reproducible environments |
| **[Dev Container](https://xum.cdr.dev/runtime/devcontainer.md)** | A container from devcontainer.json | Projects with existing devcontainer configs |

## Supported combinations

| Project \ Workspace | None | Worktree | Docker | Dev Container |
| - | - | - | - | - |
| Local | Yes | Yes | Yes | Yes |
| SSH | Yes | Yes | — | — |
| Coder | — | Yes | — | — |

Combinations marked "—" are listed in the picker but disabled until a backend supports them.

**SSH + None** runs every workspace directly in an existing directory on the host (for example `~/src/my-app`). Xum does not sync, check out, move, or delete anything in that directory, and it does not need a local git repository.

## Choosing a Runtime

Pick both when creating a workspace: the environment chip under the workspace name opens a panel where *Run on* selects the project isolation and *Isolation* selects the workspace isolation. Set the defaults, and turn options on or off, in **Settings → Runtimes**, globally or per project.

Configs written by older versions (a single default runtime) are migrated automatically, and the old field is still written so you can downgrade.

## Init Hooks

[Init hooks](https://xum.cdr.dev/hooks/init.md) and agent bash tool executions can detect the runtime type via the `XUM_RUNTIME` environment variable:

* `local` — Local project, no workspace isolation
* `worktree` — Local project, worktree isolation
* `ssh` — SSH project (worktree or no workspace isolation)
* `docker` — Docker runtime
* `devcontainer` — Dev Container runtime

This lets your init hook adapt behavior, e.g., skip worktree-specific setup when running in local mode.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.