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

# Get your project running

> How an agent takes a local project to running on a cloud GPU with voyager cloud: one command for a job, set up the environment once and start from it, pass secrets, serve a preview, and read the errors.

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

```sh theme={"system"}
voyager cloud run --pull out/ -- bash -c "pip install -r requirements.txt && python train.py"
```

`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](https://docs.voyager.so/api/machines/files.md)). 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](https://docs.voyager.so/api/machines/budgets.md).
* 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:

```sh theme={"system"}
m=$(voyager cloud lease render-lite --wait --yes)
voyager cloud push $m . .            # this folder to /project itself
voyager cloud exec $m -- bash -c "python3 -m venv .venv && .venv/bin/pip install -r requirements.txt"
voyager cloud save $m my-env --note "requirements.txt as of today"
voyager cloud release $m
```

Then every job starts from it by its name (an `snp_…` id works too; `voyager cloud snapshot list` shows them):

```sh theme={"system"}
voyager cloud run render-lite --from my-env --pull out/ -- .venv/bin/python train.py
```

* 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](https://docs.voyager.so/api/machines/concepts.md#where-to-put-files).
* `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

```sh theme={"system"}
voyager cloud run --env SEED=7 --env-from-local HF_TOKEN -- python train.py
```

* `--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

```sh theme={"system"}
voyager cloud run --port 7860 -- python app.py
```

`--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:

```sh theme={"system"}
m=$(voyager cloud lease --wait --yes)
voyager cloud push $m . .
voyager cloud exec --detach $m -- python app.py
voyager cloud port $m 7860
# … later
voyager cloud release $m
```

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:

```sh theme={"system"}
voyager cloud lease --wait --yes     # prints the id; with one machine you can leave it out below
voyager cloud push . .
voyager cloud exec -- python train.py --epochs 1
voyager cloud pull out/ .
voyager cloud release
```

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](https://docs.voyager.so/api/machines/quickstart.md#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:

| Exit | Meaning | What to do |
| - | - | - |
| The command's own | Your command ran and exited with it | Read its output above |
| 1 | Voyager failed it (a lease that failed, a lost connection) | The message says whether a retry helps; retry `run` with the printed `--request-id`, which never leases twice |
| 2 | Usage, or `NO_MACHINE` / `MACHINE_AMBIGUOUS` | Fix the command; name the machine |
| 3 | Not signed in | `voyager login`, or set `VOYAGER_API_KEY` |
| 4 | Refused: plan, credits or limits | The message has the billing link; tell the user |
| 5 | The machine is gone (released or lost) | Lease another, push again |
| 6 | A `pull` (or `run --pull`) path isn't on the machine | Check the path, or that the command wrote it |
| 130 / 143 | Stopped by Ctrl-C / SIGTERM | `run` released the machine first |

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

| How | Machine ready | Code running | Cost |
| - | - | - | - |
| `run` when no machine is free in the ready pool (a cold start; nothing to install) | 192 s | 193 s | 0.6 credits |
| `run` with `pip install` each time, a machine free in the ready pool | 11 s | 36 s | 1.4 credits |
| `run --from` the setup snapshot (section 2) | 7 s | 14 s | 0.6 credits |

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.


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