Three nouns
- 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 withfrom_snapshot. See 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/projector~/.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>(orvoyager 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.
Verbs
“Lease” is something you do, not a thing you have: you lease a machine.
Paths are relative to
https://api.voyager.so/v1/machines. The MCP tools have the same verbs: create_machine, run_command, snapshot_machine, pause_machine, resume_machine, release_machine.
Machine states
A machine’sstatus 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.
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.codeTTL_EXPIRED. Resume it to go on: each resume starts the 24 hours again. - It reaches its budget. With a
budget_usd, it pauses withBUDGET_EXCEEDEDbefore 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.
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
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.For agents
Every page of these docs is also plain Markdown, and the whole site is searchable over MCP:- One page as Markdown: add
.mdto its address, for example docs.voyager.so/api/machines/concepts.md. - Index of every page: docs.voyager.so/llms.txt. All of them in one file: 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
Quickstart
Lease a machine, run a command, copy files and release it.
Machines and cost
Every option when you lease, pause, resume, snapshots and what a machine cost.