# The official base image.

> The Renest base image, ghcr.io/renest-ai/nest-base, is a minimal Ubuntu 22.04 (linux/amd64) container image for restoring nests on a rented GPU machine. It contains the renest tool, uv, s5cmd, curl, jq, tar, sha256sum, sshd and a short list of system libraries, and deliberately no torch, ComfyUI, models, CUDA toolkit or Python on PATH. Since 20261008 it also carries the build tools restores need (see below). Your nest brings its own Python and packages. Upgrade the renest tool first, because the copy in the image is older than the latest release.

Canonical page: https://renest.ai/docs/base-image

<h2 id="what">A clean starting point for restoring a nest, with the tool already installed</h2>

<p>The image is <code>ghcr.io/renest-ai/nest-base</code>. It is Ubuntu 22.04 for linux/amd64
only, and it is published under date tags. A date tag is never overwritten, so a tag always
refers to the same bytes. The current image is tagged <code>20261008</code>, with the
digest:</p>

<pre>ghcr.io/renest-ai/nest-base@sha256:4a14617e8272d32afd514a470ee565dec0864d4cc338af10f127c8b8204215ab</pre>

<p>It is a floor, not an environment. Nothing in it competes with what the nest brings, so
what you restore is what the nest recorded. You don't need it: any Linux machine with an
NVIDIA driver visible works, and the pre-flight check tells you whether it fits.</p>

<h2 id="contains">What's in it: the tool, the escape hatch's tools, sshd and a few system libraries</h2>

<ul>
  <li><code>renest</code>, on PATH at <code>/usr/local/bin/renest</code>. It runs on its own
  Python under <code>/opt/renest</code>, which is not on PATH.</li>
  <li><code>uv</code> and <code>uvx</code>, which install the Python version and packages
  the nest's lock names.</li>
  <li><code>s5cmd</code>, for transfers.</li>
  
  <li><code>curl</code>, <code>jq</code>, <code>sha256sum</code>, <code>tar</code> and <code>uv</code>: everything the <a href="/docs/escape-hatch">escape hatch</a> needs.</li>
  <li><code>sshd</code>, with password login off and root login by key only.</li>
  <li>System libraries that image and fine-tuning workflows load at runtime and that a
  minimal Ubuntu leaves out: the X11 client libraries (<code>libx11-6</code>,
  <code>libxcb1</code>, <code>libxau6</code>, <code>libxdmcp6</code>, <code>libxext6</code>),
  OpenGL (<code>libgl1</code>, <code>libglx0</code>, <code>libglvnd0</code>) and GLib
  (<code>libglib2.0-0</code>). Each one is on the list because a real run loaded it, or
  failed without it.</li>
</ul>

<p>The versions of <code>uv</code>, <code>s5cmd</code> and <code>renest</code> built into the
image are recorded in <code>/opt/renest/versions.env</code>.</p>

<h2 id="not">What's deliberately not in it, and what that means for you</h2>

<ul>
  <li><strong>No torch, no ComfyUI, no models.</strong> The nest brings them.</li>
  <li><strong>No CUDA toolkit.</strong> PyTorch wheels carry their own CUDA runtime. What
  matters is the host's GPU driver, which the pre-flight check compares with the nest's
  lock.</li>
  <li><strong>No Python on PATH.</strong> The restore installs the exact Python version the
  nest recorded. If you want a spare interpreter, run
  <code>uv python install 3.11</code>.</li>
</ul>

<p>Since <code>20261008</code> the image also carries <strong>git, git-lfs and a C
compiler</strong> (<code>build-essential</code>). Restores need git for packages a nest
installs from a Git address, git-lfs for node folders that keep large files in LFS, and a
compiler for workflows that compile GPU kernels while they run (some triton paths). On an
older image, or any other machine, <code>renest restore</code> and <code>renest start</code>
offer to install whichever of these is missing.</p>

<p>On vast.ai, the platform puts its own <code>/usr/bin/python3</code> into the container
when it starts. That interpreter is incomplete (no <code>ensurepip</code>, no
<code>venv</code>) and doesn't come from this image. Don't build a virtual environment on it.
The restore uses the Python that uv installs.</p>

<p>From the 20261008 image on, it also carries <code>git</code>, <code>git-lfs</code> and <code>build-essential</code> (a C compiler), for nodes and packages that build from source.</p>

<h2 id="upgrade">Upgrade the renest tool before you restore</h2>

<p>The copy of <code>renest</code> in the image is the release that was current when the
image was built. It is older than the latest release, so it may not know everything a newer nest contains: a copy that predates a nest's format warns and ignores the parts it doesn't know, such as the model caches kept under the home folder. It also lacks the newer checks for a GPU that can't start and the file list for nests handed to you. Make this the first thing you run once you're connected:</p>

<pre>$ uv tool install --upgrade renest
$ export PATH="$HOME/.local/bin:$PATH"
$ renest --version</pre>

<p>The version at the bottom of this page is the latest release. Run <code>renest --version</code> to see which copy you have, and compare it with the latest release below.</p>

<h2 id="boot">At start-up it creates /workspace, makes fresh SSH host keys and starts sshd</h2>

<p>The image ships with no SSH host keys, so no two machines share them. Its start script
(<code>/opt/renest/onstart.sh</code>) does the following each time the container starts,
and is safe to run again:</p>

<ul>
  <li>creates <code>/workspace</code>;</li>
  <li>generates SSH host keys and starts <code>sshd</code> on port 22;</li>
  <li>on RunPod, adds the public key from your account settings (passed in as
  <code>PUBLIC_KEY</code>) to <code>/root/.ssh/authorized_keys</code>;</li>
  <li>prints the host's NVIDIA driver version, and puts it in the login message.</li>
</ul>

<p>On RunPod, leave the template's start command empty; the image runs the script itself.
On vast.ai in SSH mode the platform doesn't run the image's own start-up, so the template
must set the on-start script to <code>mkdir -p /workspace &amp;&amp; bash
/opt/renest/onstart.sh</code>. Without it, nothing listens on port 22 and you can't connect.
See <a href="/docs/guide-runpod#start">Renest on RunPod</a> and
<a href="/docs/guide-vast">Renest on vast.ai</a>.</p>

<h2 id="templates">Templates on RunPod and vast.ai are set up with this image</h2>

<ul>
  <li><strong>RunPod:</strong> Open the Renest template on RunPod: https://renest.ai/go/runpod The template pins the
  image by digest.</li>
  <li><strong>vast.ai:</strong> Open the Renest template on vast.ai: https://renest.ai/go/vast The template pins the date
  tag, which is never overwritten.</li>
</ul>

<p>The hosted Renest service is run by the same people who make this image. Renest doesn't
rent machines: the machine and its bill are in your own account with the platform.</p>

<h2 id="licence">The image has no single licence, so its metadata says NOASSERTION</h2>

<p>The image mixes Ubuntu packages (many under GPL or LGPL), <code>uv</code> (MIT or
Apache-2.0), <code>s5cmd</code> (MIT), and the <code>renest</code> tool, which is
source-available and not open source. No single licence covers all of it, so the image's
licence label is <code>NOASSERTION</code>. Each component keeps its own licence.</p>

<p>Inside the image, <code>/usr/share/doc/renest-floor/</code> holds the notices, the
written offer for the source code of the GPL and LGPL components, a list of the Ubuntu
packages and their versions, and the licence texts. To get that source from us, see the
<a href="/docs/source-offer">source code offer</a>. For the licences of Renest's own
parts, see <a href="/docs/licensing">Licensing</a>.</p>

<h2 id="other">Any image works; this one is the default when a nest's own image is gone</h2>

<p>A nest records the image it was packed on. If you'd rather use that image, or another
one you already use, you can. The restore needs only a Linux machine where the GPU driver
is visible, and the pre-flight check says whether it fits. If the nest's own image is no
longer available, this one is the replacement to reach for. When choosing another, compare
three things rather than the image name: the glibc generation (the same or newer, never
older), the Python version (the restore installs it either way), and the host driver against
the nest's CUDA line. <code>renest doctor</code> checks the last one.</p>