Guides

Renest on RunPod.

To restore a nest on RunPod, start a pod from the Renest base image, upgrade the renest tool, and paste the restore command from your drive into /workspace. Renest checks the machine first, brings back every file and dependency and checks each one against its recorded checksum, then starts the app and runs the packed workflow once. If the pod turns out broken, destroy it, rent another and paste the same command.

1 · The nest decides the GPU and disk, and the pre-flight check has the final say

GPU. The card doesn't have to match the one the nest was packed on. What matters is whether this machine can run what the nest carries. Before downloading anything, the pre-flight check compares the machine with the nest. It checks the GPU architecture against the compiled code in the nest, the host driver against the CUDA line in the dependency lock, the video memory the working run was seen using, and whether the GPU can actually be used. If a card can't run the nest, the check refuses it up front, instead of letting the restore die half an hour into a paid rental.

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

On the pod, --plan runs the full machine check and lists everything the restore would do, then stops before fetching anything.

Disk. Start from the nest's size, shown on its page in your drive and in the 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. On RunPod, anything under /workspace lives on the pod's volume disk; other paths live on the container disk, which is cleared when the pod stops. This guide pastes the command from /workspace, so the restore lands in /workspace/run: size the volume disk for the nest. Pasted from another folder, such as /, the same command restores into /run on the container disk. That works if the container disk is big enough, but what's there is gone when the pod stops.

For GPU generations and where your bucket sits relative to the machine, see the field notes on storage, GPUs and prices.

2 · Start from the Renest base image, or from any 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 RunPod → This is the platform's referral link. Opening the link takes you to RunPod's deploy page with the settings below already filled in. The hosted Renest service is run by the same people who make this image.

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

• Container image: pinned by digest, so the pod boots exactly these bytes:

  ghcr.io/renest-ai/nest-base@sha256:e31d287a7244cd04f527b03693a7b623c514ec828ae8a5a98072b20264f928d8

  (This is the image tagged 20260913. Date tags are never overwritten.)
• Container start command: leave it empty. The image's own start script starts sshd, generates fresh host keys, installs your SSH key, creates /workspace and prints the host's driver version.
• Expose TCP ports: 22. Add HTTP port 8188 as well if you want to open ComfyUI through RunPod's web address after the restore (you can also use an SSH tunnel instead, see step 7).
• SSH key: RunPod passes the public key from your account settings into the pod as PUBLIC_KEY, and the image writes it to authorized_keys. This guide connects over SSH.

Two limits 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 RunPod PyTorch template, or any Linux image with an NVIDIA driver visible, is fine: install the tool in step 3 and the pre-flight check tells you whether the machine is suitable. The nest installs its own Python, so the template's Python version doesn't matter.

3 · Install the tool, 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"

The export line matters on a fresh pod. Without it, renest answers command not found. --upgrade moves an older install to the latest version and does nothing on a clean machine. If you'd rather not use uv, running pip install renest in an environment with Python 3.11 or newer works too, but it installs into whatever environment is active.

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 and give it a label such as "my RunPod box". It is shown once. On the pod, 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 (read -rsp "Access key: " RENEST_TOKEN; export RENEST_TOKEN). It lasts only as long as the shell. If both are set, the environment variable wins.

Be clear about where the key now lives. A file on a rented pod stays on that pod's disk after you log out. Don't bake it into a template or an image, don't commit it, and revoke it in Settings → Access when you're done with the pod. Your account key is the only credential this path puts on the pod. 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, from the pod's terminal:

$ 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, so a missing key costs you nothing.
• --workflow: must be exported in API format (Export (API) in ComfyUI). For fine-tuning, use --framework kohya|llamafactory --run-record run.json instead.

Pack again from the same folder and Renest adds a new version to the same nest. Use --new-nest to start a separate one. Prefer a button? The ComfyUI panel packs to the pod's disk, but it doesn't upload, and on a pod it needs an SSH tunnel.

6 · Restore 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. It writes the code to grant.json and runs the restore. Paste it from /workspace, so that ./run lands on the volume disk (step 1):

$ 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 the same code works on a replacement pod.

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 --listen 0.0.0.0, expose HTTP port 8188 on the pod (or tunnel over SSH), and open it in your browser. 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 --listen 0.0.0.0. It runs exactly the command the block printed, from the same folder, with the restored Python environment, and --listen changes only the address that command already names. --dry-run prints the command and stops. 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. Either expose HTTP port 8188 on the pod and open RunPod's web address for that port, or skip the port and tunnel over SSH: ssh -N -L 8188:127.0.0.1:8188 root@<pod-address> -p <ssh-port>, then browse to http://127.0.0.1:8188. Over the tunnel, plain renest start --dir /workspace/run is enough.
• 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 a pod misbehaves (the GPU disappears, the app can't see CUDA, the disk is slower or smaller than advertised), don't spend time repairing it: copy off anything you want to keep, terminate it, start another pod 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

• The pre-flight check refuses. You'll see a plain reason: not enough disk, a driver too old for the lock's CUDA line, a GPU architecture the nest's compiled code doesn't support. This is the check doing its job before you pay for a download. Rent a machine that fits. --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. It warns rather than refuses, because the fault sometimes clears. 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. Stop that pod, 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 stop the pod.

Copy what you need, then stop or terminate the pod

A running pod is billed whether or not you're using it. Before you stop it:

1. Copy off your outputs, and anything from renest support you want to keep.
2. If you put an access key on the pod, revoke it in Settings → Access.
3. Stop keeps the volume disk, which RunPod still charges for. Terminate deletes the pod and all data that isn't on a network volume. Your nest is safe either way: it's on your drive, and a new restore code, or the unexpired old one, brings it back on the next pod.