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

# Cloud machine concepts

> The three things you work with on Voyager cloud GPUs (machine, snapshot, volume), every other term defined once, and each machine state with whether it bills and what it keeps.

Voyager cloud GPUs have three things you keep track of: **machines**, **snapshots** and **volumes**. Every other word on these pages is something you do to one of them, or a setting of one.

For example: you lease a machine, install your tools and save a snapshot. Tomorrow you lease a new machine from that snapshot and it starts with everything already installed, while your datasets wait on a volume that outlives both machines.

## Three nouns

| Noun | What it is | Id | How long it lasts |
| - | - | - | - |
| **Machine** | A Linux computer with one or more NVIDIA GPUs in Voyager's cloud, with its own disk. You run commands on it and copy files to and from it. | `mch_…`, or the name you gave it | Until you release it. It keeps its id when you pause and resume it. |
| **Snapshot** | A saved copy of a machine's disk: your files under `/project` and any software you installed. Not running programs, memory or what was on the GPU. | `snp_…`, the name you saved it under (the newest of that name), or a machine's name (its newest snapshot) | 30 days after it was saved, or until you delete it. |
| **Volume** | A named disk outside any machine, mounted at `/persist`. The next machine that names it gets the same files. | its name | Kept when a machine is released. |

* **Snapshots** come two ways: you save one (`POST /v1/machines/{id}/snapshots`, `voyager cloud snapshot`), or Voyager saves one by itself every time a machine pauses. A workspace keeps up to 100 snapshots it saved; the automatic ones don't count. Lease a new machine from any snapshot with `from_snapshot`. See [Snapshots](https://docs.voyager.so/api/machines/machines.md#snapshots). To set a machine up once and start others from it, save it under a name (`voyager cloud save <machine> my-env`) and lease from that name: `voyager cloud lease --from my-env`, or `"from_snapshot": "my-env"`. Saving the same name again moves it to the newer disk. Keep installs in `/project` or `~/.local` (`pip install --user`): a save that changed system folders keeps the whole disk and starts several times slower.
* **Volumes** are attached only by `voyager machine lease --volume <name>` (or `voyager machine fork … --volume <name>`) for now. `voyager cloud lease`, the REST API and the MCP server don't attach them. A volume belongs to the workspace, not to one machine. Keep data and checkpoints on it, not Python environments: see [Where to put files](#where-to-put-files).

## Verbs

"Lease" is something you do, not a thing you have: you lease a **machine**.

| Verb | What happens | REST API | CLI |
| - | - | - | - |
| **Lease** | Ask for a new machine. Billing begins when it's `ready`. | `POST /v1/machines` | `voyager cloud lease` |
| **Run** | Run a command on a ready machine. A long one runs as a **job**. | `POST /{id}/run` | `voyager cloud exec` |
| **Push** / **pull** | Copy files to or from the machine. | `POST /{id}/files/upload`, `…/download` | `voyager cloud push`, `pull` |
| **Snapshot** | Save the disk now, without stopping. | `POST /{id}/snapshots` | `voyager cloud snapshot` |
| **Save** | Save the disk under a name, to start other machines from it. | `POST /{id}/snapshots` with `name` and `replace` | `voyager cloud save <machine> <name>` |
| **Pause** | Save the disk to a snapshot and give the GPU back. Billing stops. | `POST /{id}/pause` | `voyager cloud pause` |
| **Resume** | Start a paused machine again on a fresh GPU, from its latest snapshot. Same id; billing starts again at `ready`. | `POST /{id}/resume` | `voyager cloud resume` |
| **Release** | Finish. The GPU is given back and the cost is settled. Final. The disk is deleted unless you keep it with `?snapshot=true` (`--snapshot`), which saves it first as a pause does (billed for the seconds it takes); then `lease --from <machine>` starts from it. Pause always keeps it. | `DELETE /{id}` | `voyager cloud release [--snapshot]` |

Paths are relative to `https://api.voyager.so/v1/machines`. The [MCP tools](https://docs.voyager.so/api/machines/mcp.md#tools) have the same verbs: `create_machine`, `run_command`, `snapshot_machine`, `pause_machine`, `resume_machine`, `release_machine`.

## Machine states

A machine's `status` is one of `starting`, `ready`, `paused`, `released` or `failed`. Each covers one or more steps; the table shows every step, what bills and what is kept.

| Step | `status` | What's happening | Billed? | What is kept |
| - | - | - | - | - |
| Requested | `starting` | Voyager accepted the request and is finding a GPU. | No | Nothing on a machine yet. The snapshot it will start from, if any, and any volume. |
| Allocating | `starting` | The GPU is starting and the disk is being set up, from the snapshot when there is one. | No | As above. |
| Resuming | `starting` | A paused machine starting again on a fresh GPU. | No | Its latest snapshot, being restored. |
| Ready | `ready` | Running. Commands and file transfers work. | **Yes**, per second | Everything: the disk, running programs, memory, and `/persist` if a volume is attached. |
| Pausing | `paused` | Jobs are stopped and the disk is being saved. | **Yes**, until the disk is saved and Voyager stops the GPU | The disk, being saved to a snapshot. |
| Paused | `paused` | The GPU is given back. Commands and file transfers answer `MACHINE_PAUSED` until you resume. | No | The disk, in the automatic snapshot. Like every snapshot it expires 30 days after it was saved, so resume within that time. Running programs, memory and GPU state are gone: resume restarts nothing. |
| Retained | `paused` | Paused with the GPU kept, only from `voyager machine pause --mode retain`. Work still runs on it. | **Yes**, per second | Everything, as when ready. |
| Releasing | `released` | The GPU is being given back and the cost settled; with `snapshot=true`, the disk is saved first. | Until Voyager stops the GPU, including the seconds the disk takes to save | Nothing on the machine; with `snapshot=true`, the disk, being saved to a snapshot. |
| Released | `released` | Finished, final. `cost` is the total; unused held credits go back to the workspace. | No | Snapshots, until they expire, and volumes. The machine's disk is deleted, unless it was released with `snapshot=true`: then it is a snapshot you can lease from. |
| Failed | `failed` | It never became ready. `error` says why. | No | Nothing. |

> [!WARNING]
>
> A machine bills for every second it's `ready`, whether or not anything runs on it. Release it when you're done; pause it to stop billing and keep its disk.

### When a machine pauses by itself

A ready machine pauses on its own, saving its disk the same way, when:

* **It's idle.** No command, no file transfer and no busy GPU (any reading above 10%) for its **idle timeout**: 15 minutes unless you set `idle_timeout` (30 seconds to 7 days) when you lease it. Work you start from a shell rather than a command still counts while it keeps the GPU busy.
* **It reaches its lifetime.** A machine runs for at most 24 hours from when its GPU starts, then pauses with `error.code` `TTL_EXPIRED`. Resume it to go on: each resume starts the 24 hours again.
* **It reaches its budget.** With a `budget_usd`, it pauses with `BUDGET_EXCEEDED` before it spends more.
* **The workspace runs out of credits.** It pauses with `INSUFFICIENT_CREDITS`.
* **It stops answering.** When every call to it has failed for 10 minutes, it pauses with `MACHINE_UNRESPONSIVE`.

If the GPU host loses a machine under you (it ran out of memory, or the hardware was reclaimed), the call in flight answers `410` `MACHINE_LOST`, and Voyager starts the machine again on a new GPU with the same id. It restores the latest snapshot, or starts from the bare image when there is none: anything written since is gone. The machine's `error` says `MACHINE_RESTARTED`, and so do jobs that run on it. The replacement bills from your first command, file transfer, port or snapshot on it. When it can't be replaced (its lifetime or budget is nearly used up, or no GPU or credits are free), it stays `paused` with `MACHINE_LOST` instead: resume it when you're ready.

## Where to put files

| Where | Put here | Why |
| - | - | - |
| `/project`, on the machine's own disk | Code, inputs, outputs, and every environment: Python venvs, conda, `pip install`, model code, caches. | Fast for many small files. Kept by pause and snapshots; deleted at release. |
| `/persist`, on a volume | Datasets, large outputs and checkpoints that must outlive the machine. | Kept across machines. |

> [!WARNING]
>
> Don't install a Python environment on a volume. A newly attached volume reads many small files very slowly, while large files stream fine: importing an environment's packages from a fresh volume once kept a training job at 0% GPU for 16 minutes.

To reuse an environment, install it on the machine's disk once, save a snapshot and lease later machines with `from_snapshot`. Or keep a `.tar` of the environment on the volume and unpack it to the machine's disk when a job starts: one large file reads fast.

## Other terms

Each is defined here once; the other pages use them the same way.

| Term | Meaning |
| - | - |
| **Preset** | A named choice of GPU and image: `render` (the default), `render-lite` or `compute`, plus `render-2x` and `render-4x` with more GPUs on plans that allow them. See [Presets](https://docs.voyager.so/api/machines/overview.md#presets). |
| **GPU** | The NVIDIA card a machine runs on, such as `RTX-PRO-6000`. A preset picks one; `gpu` overrides it. |
| **Image** | The software a machine starts with, such as `creative-cuda@v3`: CUDA, Python, FFmpeg, Blender tools and Vork. |
| **Job** | One command running on a machine (`mjb_…`): `running`, `succeeded`, `failed` or `canceled`. |
| **Idle timeout** | `idle_timeout`: seconds with no command, file transfer or busy GPU before a ready machine pauses itself. |
| **Budget** | `budget_usd`: the most a machine may spend, in US dollars. It pauses when it gets there. |
| **Credits** | Voyager credits, which every machine bills against. Prices are at [voyager.so/pricing](https://voyager.so/pricing); live rates come from `GET /v1/machines/presets`. |
| **Hold** | Credits set aside from the workspace while a machine runs; whatever it didn't spend goes back at release. |
| **Port link** | A `https://….run.voyager.computer/` link to a port on a ready machine. See [Ports](https://docs.voyager.so/api/machines/files.md#ports). |

## For agents

Every page of these docs is also plain Markdown, and the whole site is searchable over MCP:

* **One page as Markdown:** add `.md` to its address, for example [docs.voyager.so/api/machines/concepts.md](https://docs.voyager.so/api/machines/concepts.md).
* **Index of every page:** [docs.voyager.so/llms.txt](https://docs.voyager.so/llms.txt). **All of them in one file:** [docs.voyager.so/llms-full.txt](https://docs.voyager.so/llms-full.txt).
* **Docs search over MCP:** `https://docs.voyager.so/mcp`, no sign-in. Claude Code: `claude mcp add --transport http voyager-docs https://docs.voyager.so/mcp`.

## Next

> [card] [Quickstart](https://docs.voyager.so/api/machines/quickstart.md)
>
> Lease a machine, run a command, copy files and release it.

> [card] [Machines and cost](https://docs.voyager.so/api/machines/machines.md)
>
> Every option when you lease, pause, resume, snapshots and what a machine cost.


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