Skip to main content
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

  • 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. 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.

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’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.
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

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.

For agents

Every page of these docs is also plain Markdown, and the whole site is searchable over 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.