Guides

Renest on vast.ai.

To restore a nest on vast.ai, start an instance from the Renest base image with its on-start script set (vast skips the image's own start-up in SSH mode, so without that script the instance can't be reached), upgrade the renest tool, and paste the restore command from your drive into /workspace. Filter offers by disk size and download speed and let the pre-flight check judge the GPU. If the instance turns out broken, destroy it, rent another and paste the same command.

1 · Filter offers by disk, download speed and GPU, then let the pre-flight check decide

Disk space. On vast, you choose the disk size when you create the instance, so get it right up front. Start from the nest's size, shown on its page in your drive and in the ComfyUI panel's Estimated size. Add room for the Python environment the restore installs from the lock, which for image and training stacks is often several gigabytes on its own. The pre-flight check does this sum for the disk that holds the folder you restore into, and checks any other disk the nest writes to (a model cache in your home folder, for example) separately. If there isn't room, it stops with Only … GiB free, and this nest needs … GiB before it starts downloading.

The disk that needs the room is the one holding your --dir. --dir has no default, and the command your drive gives you says --dir ./run, which is relative to the folder you paste it in. This guide pastes the command from /workspace, so the restore lands in /workspace/run, on the instance's disk: size that disk for the nest.

Download speed. A restore downloads the whole nest and then its dependencies, so the offer's download speed matters more than it does for most rentals. The pre-flight check measures the link against the size of what it's about to fetch. It warns on a slow link and refuses one too slow to finish. Picking an offer with a high download speed avoids that refusal. Machines in the same region as your bucket usually do better; see the field notes on storage, GPUs and prices.

GPU and driver. The card doesn't have to match the one the nest was packed on. Before downloading, the pre-flight check compares the GPU architecture with the compiled code in the nest, the host driver with the CUDA line in the dependency lock, and the video memory the working run was seen using. It also checks whether the GPU can actually be used. Filtering by reliability narrows the list; the check has the final say.

You can ask before you rent. On any computer with the tool installed, this checks whether everything the nest does not carry can still be fetched, and needs no GPU:

$ renest restore --grant grant.json --dir ./run --check-only

2 · Start from the Renest base image with the on-start script set, or from a template you already use

The Renest base image is a clean starting point with the tool preinstalled

The base image is a minimal Ubuntu 22.04 (linux/amd64) image for restoring nests. It contains the renest tool, uv, s5cmd, curl, jq, tar, sha256sum, sshd, and the system libraries that image and fine-tuning workflows commonly load at runtime. By design it has no torch, no ComfyUI, no models, no CUDA toolkit and no Python on PATH. Your nest brings its own Python version and packages, and the restore puts them back.

Template link. Open the Renest template on vast.ai → This is the platform's referral link. The template has the image, launch mode and on-start script below already set. The hosted Renest service is run by the same people who make this image.

To set it up by hand, create a template with:

• Image path / tag:

  ghcr.io/renest-ai/nest-base:20260913

  vast needs the registry host (ghcr.io) for images outside Docker Hub. The image is public, so leave the registry login empty. Date tags are never overwritten: this one always points to digest sha256:e31d287a7244cd04f527b03693a7b623c514ec828ae8a5a98072b20264f928d8.
• Launch mode: SSH. Docker options: -p 22:22. Add -p 8188:8188 as well if you want to reach ComfyUI directly after the restore, instead of through an SSH tunnel.
• On-start script (required; don't leave it empty):

  mkdir -p /workspace && bash /opt/renest/onstart.sh

vast won't boot this image into a reachable state without the on-start script

In SSH and Jupyter launch modes, vast doesn't run the image's own start-up script (its entrypoint). The base image deliberately ships without SSH host keys, so that a public image doesn't give every instance the same keys. The on-start script generates the keys at first boot and starts sshd. It also creates /workspace and prints the host's driver version. Without the script, the instance shows as running but nothing listens on port 22, and you can't connect.

The same applies to any image you bring yourself. If an image relies on its entrypoint to start services, put the equivalent commands in the on-start script.

Three more things that are specific to vast:

• The first launch can be slow. The host has to download the image before the instance can be reached, and on a slow link that can take a long time. Give it time before deciding something is wrong; how long it takes says little about the image itself.
• vast adds its own /usr/bin/python3, and it is incomplete (no venv, no ensurepip). It doesn't come from the base image. Don't build a virtual environment on it. uv installs its own interpreter, and that is what the restore does anyway.
• Environment variables from the image or template don't reach your SSH session. Don't put your access key in the template's environment variables: it won't be visible where you run renest, and it would sit in the template. Use the config file in step 4.

Two limits of the base image to know before you rent:

• There is no C compiler. A workflow that compiles GPU kernels while it runs (some triton paths) won't run on this image. Runtime-level base images generally don't include one either.
• It has no single licence. The image mixes Ubuntu packages (many GPL/LGPL), permissively licensed binaries, and the source-available renest tool, so its licence metadata says NOASSERTION. Notices, the written offer for source code and licence texts are in /usr/share/doc/renest-floor/. See the source code offer.

Any other template works too

Renest doesn't need our image. A vast PyTorch or CUDA template, or any Linux image with the NVIDIA driver visible, is fine: install the tool in step 3 and the pre-flight check tells you whether the machine is suitable. If the template has no /workspace, create it (mkdir -p /workspace) or restore somewhere else with enough room.

3 · Install the tool with uv, or upgrade it on the base image

# no uv yet?
$ curl -LsSf https://astral.sh/uv/install.sh | sh
$ source ~/.bashrc
# then install renest (or upgrade an older copy)
$ uv tool install --upgrade renest
$ export PATH="$HOME/.local/bin:$PATH"

Prefer uv over pip on vast. The python3 vast adds can't create environments, while uv brings its own. The export line matters on a fresh instance; without it, renest answers command not found. --upgrade moves an older install to the latest version and does nothing on a clean machine.

On the base image, renest is already on PATH, but the copy baked into the image (tag 20260913) is older than the latest release. It has no renest start and doesn't print the What's next lines described in step 7. Upgrade it the moment you're connected. If you skip this, the renest start command in step 7 doesn't exist:

$ uv tool install --upgrade renest
$ renest --version

4 · An access key is needed to pack to your drive, not to restore

Restoring doesn't need a key. The restore code from your drive is itself the credential. Packing with --dest hosted does need one, and so do renest list and renest export. There is no renest login command.

Create a key in the web console under Settings → Access: in the Access keys section, choose New key. It is shown once. On the instance, write it into the tool's config file, which only you can read:

$ mkdir -p ~/.config/renest
$ ( umask 077; read -rsp "Access key: " k; echo
printf '[auth]\ntoken = "%s"\n' "$k" > ~/.config/renest/config.toml )

Pasting at the prompt keeps the key out of your shell history, and umask 077 creates the file as 0600. If config.toml already has other settings, add the [auth] section to it instead of overwriting it.

For a single session, you can use the RENEST_TOKEN environment variable instead, set in the shell itself (read -rsp "Access key: " RENEST_TOKEN; export RENEST_TOKEN), not in the template. If both are set, the environment variable wins.

Be clear about where the key now lives. A file on a rented instance stays on its disk after you log out. Don't commit it or put it in a template, and revoke it in Settings → Access when you're done with the instance. Your account key is the only credential this path puts on the instance. Bucket keys never go there.

5 · Pack the run once it has worked

Get the workflow rendering, or the training run finished, first. Renest captures only setups that have already produced a result. Then:

$ renest pack --dir /workspace --workflow workflow-api.json \
--out /workspace/nests --dest hosted

• --dir (required): the folder that holds ComfyUI/.
• --out (required for a real pack): where the nest is written on this machine. --dry-run prints the plan without it.
• --dest hosted: also upload it to your drive. Without this flag, the nest exists only in --out. The access key is checked before packing starts.
• --workflow: must be exported in API format (Export (API) in ComfyUI). For fine-tuning, use --framework kohya|llamafactory --run-record run.json instead.

The ComfyUI panel can pack to the instance's disk too, but it doesn't upload, and on a rented machine it needs an SSH tunnel.

6 · Restore into /workspace with the command your drive gives you

In your drive, open the nest and choose Restore. Pick how long the restore code should last: 1 day, 3 days or 7 days. Copy the pod command, then paste it on the instance from /workspace, so that ./run lands where step 1 sized the disk:

$ cd /workspace
$ cat > grant.json <<'RENEST_GRANT'
{ …your restore code… }
RENEST_GRANT
$ renest restore --grant grant.json --dir ./run

Treat the code as a password. Anyone holding it can restore that version until it expires, and you can revoke it from the drive at any time. It is not tied to a machine, so if an instance turns out to be bad, the same code works on the next one.

The restore checks the machine first, downloads every file and checks it against its recorded checksum, installs dependencies from the lock, then starts the app and runs the packed workflow once. A restore has succeeded when that run produces output (an image, or a non-empty training artifact), not merely when the command exits cleanly. If the connection drops, run the same command again. Files already on disk that match their checksums are kept.

7 · After the restore, your image is in the output folder and ComfyUI starts with renest start

Where is my image, and how do I open ComfyUI? Those are the first two questions after a restore. Short answers: the test image is in /workspace/run/ComfyUI/output; start ComfyUI with renest start --dir /workspace/run, then open it through an SSH tunnel from your own computer. The full walk-through, for any machine, is After the restore.

The restore starts the app only for its own check, then stops it. Its closing lines are the last thing it prints, below the JSON report: a ✅ Done line followed by a What's next: block. That block is built from this nest's own manifest, so its commands and paths are the ones to use. For an image nest restored into /workspace/run whose recorded start command listens on 127.0.0.1, it contains lines like these:

[restore] What's next:
[restore]   · Start it yourself: cd /workspace/run/ComfyUI && /workspace/run/.venv/bin/python main.py --listen 127.0.0.1.
[restore]   · That command listens on 127.0.0.1, which answers this machine only — right for the
check that just ran, not for your browser. To reach it from outside, change that one
value to 0.0.0.0 (or run renest start --dir /workspace/run --listen 0.0.0.0, which
does it for you).
[restore]   · Started that way it listens on port 8188. On a rented GPU box, reaching it from your
own browser also means exposing that port in your provider's panel — the check never
did that for you.
[restore]   · Images render into /workspace/run/ComfyUI/output — that is where yours is.
[restore]   · The workflow that produced the test render: /workspace/run/.renest/staging/workflow.json.
Drop it into the app to start from what worked.
[restore]   · Moving to another machine? The same restore command works there too — it reuses what is
already fetched and carries on.
[restore]   · Or let the tool do it for you: renest start --dir /workspace/run

If the recorded command names no address at all, the second and third lines are replaced by one: Started that way it listens on port 8188. On a rented GPU box, reaching it from your own browser means it has to be listening on 0.0.0.0 and that port exposed in your provider's panel — the check never did either for you.

In practice, for ComfyUI:

• Start it with renest start --dir /workspace/run. It runs exactly the command the block printed, from the same folder, with the restored Python environment. --dry-run prints the command and stops. To reach it without a tunnel, add --listen 0.0.0.0: it changes only the address that command already names. If the recorded command names no address, --listen refuses rather than invent a flag; then run the printed command yourself with --listen 0.0.0.0 added:
  Shell

  $ cd /workspace/run/ComfyUI
  $ /workspace/run/.venv/bin/python main.py --listen 0.0.0.0 --port 8188

• Open it. The simplest way on vast is an SSH tunnel from your own computer, using the SSH address and port vast shows for the instance: ssh -N -L 8188:127.0.0.1:8188 root@<instance-address> -p <ssh-port>, then browse to http://127.0.0.1:8188. If you added -p 8188:8188 when you created the instance and started ComfyUI with --listen 0.0.0.0, vast maps the port to a random external port on the machine's public address, so connect to that port rather than to 8188.
• Find your images in the output folder the block names.
• Drag the workflow file it names into ComfyUI to start from what worked.
• For a fine-tuning nest, the block instead names the output file the nest was packed to produce, and the command to run the training again.

If the block has no start command, that's because the nest doesn't record one. It doesn't guess.

If the machine turns out broken, destroy it and paste the same command on another

The restore code is not tied to a machine. If an instance misbehaves (the GPU disappears, the app can't see CUDA, the download crawls), don't spend time repairing it: copy off anything you want to keep, destroy it, start another instance from the same template, and paste the same restore command from /workspace. Nothing is wrong with your nest, and the code works until it expires or you revoke it. If it has expired, issue a new one from the nest's Restore page.

When it stops, the message names the problem, and a replacement machine fixes most machine problems

• You can't connect at all. Check that the on-start script is set and give the first launch time (see step 2). This happens before Renest is involved.
• The pre-flight check refuses. You'll see a plain reason: not enough disk, a link too slow for the download, a driver too old for the lock's CUDA line, a GPU architecture the nest's compiled code doesn't support. Rent an offer that fits. On vast, disk size can't be changed afterwards, so a disk refusal means a new instance. --force goes ahead anyway, but only use it if you know better than the check.
• A passed check doesn't guarantee the GPU is usable when the app starts. The check runs a full nvidia-smi. On a faulty host it warns with a line that begins Full nvidia-smi failed here and ends replace the machine rather than re-downloading. A host can also pass that check and still fail when the app starts, with No CUDA GPUs are available. Either way, nothing is wrong with your nest. Destroy that instance, start another, and paste the same restore command.
• Anything else. If the tool prints an instruction, do that one thing and run the same command again. To turn a failed run into something you can read and paste into a ticket, run renest support --dir ./run. It never goes online and never uploads. Do this before you destroy the instance.

Copy what you need, then destroy the instance

An instance costs money for as long as it exists. Before you end it:

1. Copy off your outputs, and anything from renest support you want to keep.
2. If you put an access key on the instance, revoke it in Settings → Access.
3. Stop still charges for the disk, and the GPU may be rented to someone else by the time you start it again. Destroy deletes the instance and everything on it. Your nest is safe either way: it's on your drive, and a restore code brings it back on the next instance.