Concepts

The escape hatch.

Even if Renest disappears, a nest's files and dependencies still come back, each one checked against its recorded checksum. The escape hatch is restore.sh, one plain shell script that needs only curl, jq, sha256sum, tar and uv, no account and no servers of ours. It does not start the app; that part is the renest tool's job.

The promise is narrow enough to keep: files and dependencies come back, checked

restore.sh brings a nest's files and dependencies back using only curl, jq, sha256sum (or shasum), tar and uv. It does not need Renest installed, an account, or any server of ours. Keep a copy next to your files and you can always get them back, each one checked against its recorded checksum.

It stops there. restore.sh does not start the application or run your workflow again; starting it and judging the result is the renest tool's job (see three gates). An exit code of 0 from the script proves the files and dependencies came back, and nothing more.

It ships inside every nest, and it's plain shell you can read start to finish. That is the intended way to check the claim: read it.

You run it with a restore code or a bucket address

# with a restore code
$ GRANT=code.json TARGET=/workspace bash restore.sh

# straight from a bucket you can already read
$ NEST_URL=https://<bucket>/nests/<id> TARGET=/workspace bash restore.sh

NEST_URL points at the nest folder — the one holding manifest.json. Files are fetched by their checksum, checked against the manifest, and put back where they belong.

Two optional variables:

• BLOB_BASE sets where the files are fetched from, when they don't sit in the usual place next to the nest folder. Without it, the script works it out from NEST_URL.
• PACKAGE_SOURCE points dependency installs at a closer package index, such as PACKAGE_SOURCE=https://<mirror>/simple, when installing is slow. Every package is still checked against the fingerprint recorded in the nest, so a wrong mirror stops the script instead of slipping through.

Private buckets need links signed elsewhere

The script has no openssl and never will — that's what keeps the dependency list short enough to trust. So it cannot sign links itself. For a private bucket, sign them somewhere your key already lives and pass the result in:

$ renest presign --nest <id> --out code.json
$ GRANT=code.json TARGET=/workspace bash restore.sh

If you'd rather not use Renest at all, pass presigned URLs directly with MANIFEST_URL and BLOB_MANIFEST.

The copy inside a nest is frozen, so run a current one when you can

Every nest carries a copy of the script at .renest/escape/restore.sh. That copy is frozen at the moment the nest was packed: fixes made later never reach it. It is the floor. It will still get your files back if we no longer exist. When you can, use the latest copy, which has those fixes: it ships inside the current renest package, and every newly packed nest carries it. A comment near the top of the script names the nest formats that copy reads, which is how you tell copies apart.

Be careful with a nest someone else gave you. The script inside it is their code, and running it runs their code on your machine. Use your own current copy instead, or first compare the script's fingerprint with the one listed in the nest's own file list.

It stays deliberately dumb: it informs on compatibility and stops only on trust

On compatibility it informs, it never refuses. A GPU generation the code was never compiled for, a Python or CUDA version that doesn't line up, a nest written by a newer Renest than this script knows — where renest restore blocks and makes you pass --force, the script says the same thing in the plainest terms it can and carries on. That is the whole point: a tool whose job is "work when nothing else does" cannot also be the thing that decides you may not proceed. Setup commands the nest brought with it are printed first, then run.

What it does refuse over is trust, not compatibility. It stops before installing dependencies from a server nobody recognises: that step runs someone else's code on your machine, so a warning would be useless. Name the host with RENEST_TRUSTED_HOSTS and re-run — see unrecognised dependency sources. That gate is deliberately identical in both rebuild paths; a nest that stops in one and sails through the other would be worse than either. It also stops if a nest tries to write outside the folder you pointed it at — someone else's bytes don't get to pick where they land.

It's also why the format can't grow private state: anything the manifest doesn't record, this script can't rebuild. Every format change is run through it by hand before it ships — if the escape hatch can't do it, the format doesn't get it.