Skip to main content
This page shows how to put the commands together. voyager cloud does not guess your project’s setup. You (or your agent) choose the commands, and Voyager runs them, copies files, keeps the machine’s disk and releases the machine when you’re done. Each recipe below works for any language or package manager.

1. One command for a job

run leases a machine, waits until it’s ready, pushes this folder to /project, runs the command there with its output streaming, pulls out/ back here, then releases the machine and prints how long it ran and what it cost. It exits with the command’s own code. The machine is released whatever happens: a failed command, an error, Ctrl-C or SIGTERM.
  • .git/, .venv/, node_modules/, .env files and keys are not pushed (see default excludes). A .voyagerignore file (gitignore syntax) leaves out more, such as datasets you fetch on the machine.
  • Name outputs with --pull, once per path under /project. If the command succeeded but a path isn’t there, run exits 6.
  • run render-lite …, or --gpu L40S, picks the GPU. voyager cloud presets lists them with their price.
  • --budget 5 caps what the job may spend; add --ceiling 8 to let a running command finish past $5. See Budgets.
  • stderr ends with times: ready … s · code started … s · total … s. “code started” is how long it took from the command to your code running.
Installing every time is fine when it’s quick. When the install takes minutes, set up once and start from a snapshot.

2. Set up once, then start from it

Install into the machine’s own disk, under /project, and save a snapshot:
Then every job starts from it by its name (an snp_… id works too; voyager cloud snapshot list shows them):
  • Keep what you install in the folders a snapshot saves on its own: a venv under /project (or pip install --user), and models under /project (for example HF_HOME=/project/hf; ~/.cache is not saved). When only those changed, the snapshot holds just them and a machine starts from it fast. Installing with apt or the system pip makes it save the whole disk, which starts several times slower.
  • Never install onto a volume at /persist. A volume is for data and checkpoints: an environment read from it file by file is slow. See Concepts.
  • push $m . with no destination puts the folder at /project/<folder name>. push $m . . puts it at /project, where exec and run start.
  • When requirements.txt changes, set up again and save under the same name: --from my-env then starts from the new one.
  • --from also takes a machine’s name: it starts from that machine’s newest snapshot, including the one it saved when it paused.
  • A snapshot starts on any GPU. When the GPU you ask for isn’t free, the start moves to a bigger one by itself, at the price of the one you asked for.

3. Secrets and settings

  • --env NAME=value sets a variable for the command.
  • --env-from-local NAME sends this computer’s value of NAME with the request, never on a command line here (where other users can see it in the process list). Use it for keys and tokens.
  • Values are never stored and never printed by voyager cloud; only the names are kept. Don’t push .env files: they are excluded by default.

4. A server you want to look at

--port opens a private https://….run.voyager.computer/ link to that port before your command starts and prints it on stderr. Open it once the server is up. Press Ctrl-C to stop: the machine is released. To keep a server up across several commands, lease, run it with exec --detach, open the link with port, and release when you’re done:
The link is private: it carries its token, and opens only with it. Add --public to port for a link anyone with the address can open. Share the link only with people who should reach the port.

5. Work across several calls

For a session that needs the machine between steps (look at a result, change code, run again), keep one machine:
With only one running machine, commands that act on a machine use it and say using <machine> on stderr. With several, they list them and ask you to name one. See the current machine. A machine left idle pauses itself after 15 minutes, but release it when you’re done.

When something goes wrong

Every error is one line on stderr starting with Error:, or with --json an error object with a code. The exit code says what kind:

How long it takes

Measured on 2026-11-18 with run render-lite and a small Python project (numpy, pandas, scikit-learn). “Code running” is from the command to the first line the project printed. Setting up the snapshot took one lease of 44 s (2.5 credits). Starting from it skips the install, so it pays off from the second run, and more so the longer the install.