Presets and setup#

A runtime starts from an image: one of Hesperus's presets, or an image of your own. On top of it, a setup installs your Python and system packages and runs a script, and a few basic tools are added when the image lacks them. This page explains how a preset's build is chosen for your machines, what an image of your own needs, and how the setup behaves.

Presets#

Notebooks and environments start from the same presets. Each is pinned by the digest of its image, so it is the same bytes on every machine. A preset may have several builds — NVIDIA (CUDA), AMD (ROCm), CPU — and the runtime gets the one for the machine's GPUs.

Preset (`image`)	Console	What it has	Builds (download)
`python` (default)	Python + SciPy	Python 3.13, NumPy, pandas, SciPy, scikit-learn, matplotlib, seaborn, Jupyter	CPU 1.3 GB
`python-3.12`	Python 3.12	Plain Python 3.12 on Debian 12	CPU 381 MB
`minimal`	Python (minimal)	Python 3.13 and Jupyter only	CPU 567 MB
`cuda`	CUDA dev	CUDA 12.9 toolkit (nvcc, headers) on Ubuntu 24.04, plus gcc, make, CMake, Python	NVIDIA 5.7 GB
`pytorch`	PyTorch	PyTorch 2.14, CUDA 12.6, cuDNN 9; AMD's PyTorch 2.13 on ROCm	NVIDIA 4.0 GB, AMD 20.5 GB
`ngc-pytorch`	NVIDIA NGC PyTorch	NGC PyTorch 26.09: CUDA 13, cuDNN, NCCL, TensorRT, Apex, Transformer Engine, JupyterLab	NVIDIA 11.7 GB
`huggingface`	Hugging Face	`pytorch` plus Transformers, PEFT, Datasets, Accelerate, bitsandbytes (pinned)	as `pytorch`
`jax`	JAX	NGC JAX 26.09: JAX with CUDA, Flax, Optax, Orbax, JupyterLab	NVIDIA 8.9 GB
`tensorflow`	TensorFlow	TensorFlow 2.21	NVIDIA 3.8 GB, CPU 616 MB
`spark`	Spark	Apache Spark 4.2, PySpark, Java 21, in local mode	CPU 803 MB
`rapids`	RAPIDS	RAPIDS 26.08 for CUDA 12: cuDF, cuML, cuGraph, Dask, JupyterLab	NVIDIA 6.4 GB
`vllm`	vLLM	vLLM 0.30, the release Eos serves with	NVIDIA 8.7 GB, AMD 11.7 GB
`datascience`	Data science	Python, R and Julia with their data science libraries, and Jupyter	CPU 2.4 GB
`pytorch-cuda`	PyTorch + SciPy (Jupyter)	PyTorch for CUDA 12 with the scipy stack and Jupyter	NVIDIA 5.3 GB
`tensorflow-cuda`	TensorFlow + SciPy (Jupyter)	TensorFlow 2.21 with CUDA, the scipy stack and Jupyter	NVIDIA 4.9 GB

Sizes are the compressed x86-64 download of a machine's first start; later starts on that machine reuse the image. ngc-pytorch and jax need an NVIDIA driver of the 580 series or newer. The exact images, their arm64 builds and the packages each preset adds are in the Presets reference; astra env presets lists them too.

Which build a runtime gets#

The build is chosen when the runtime starts:

No GPU asked: the CPU build, or the preset's first build (a CUDA image runs on a CPU too).
GPUs asked: the build for the GPUs of the machine it is pinned to — or, when it may run on several machines, of those machines (the ones with as many GPUs as it asks for): AMD's when most of them are AMD's, else NVIDIA's. Its GPUs are then asked of that vendor only, so a CUDA build never lands on an AMD GPU.
A preset with no build for those GPUs (RAPIDS, JAX, CUDA dev, NGC PyTorch, the Jupyter CUDA presets where only AMD GPUs are) fails to start, saying so and naming the presets that have an AMD build.
A preset built for no GPU (python, spark…) with GPUs asked: the GPUs are there, but its libraries do not use them. The form warns.

The preset cards in the console say, for your ask and your machines, which build the runtime will get and its download size, or no build for these GPUs.

An image of your own#

Choose Custom image and give its Image reference (spec.image, any registry reference, at most 512 characters; pin it by digest to get the same bytes everywhere). What it needs depends on the kind:

Kind	The image needs
A notebook's runtime	Python with pip. Jupyter Server and `ipykernel` are installed onto the drive at the first start when the image has none (`jupyter-server==2.21.1`, `ipykernel==7.4.0`). It runs as the image's user.
Shell environment	`/bin/sh`. The machine brings the SSH server.
IDE environment	`/bin/sh`, and glibc 2.28 or newer with libstdc++ (Debian, Ubuntu, RHEL, NGC images). An Alpine (musl) image fails at start, saying so: use a shell environment for it.

A runtime cannot name a registry credential yet: its image must be pullable anonymously, or already on the machine. A runtime pulls its image only when the machine does not have it, so an image pulled there once by a run with a registry credential works.

Users#

Runtime	Runs as	You log in (SSH) as, by default
A notebook's runtime on a Jupyter preset (`python`, `minimal`, `datascience`, `pytorch-cuda`, `tensorflow-cuda`)	`jovyan`, the Jupyter images' user (the container starts as root, gives `/content` to `jovyan` and drops to it)	`jovyan`
A notebook's runtime on another preset	root	root
A notebook's runtime on your image	the image's user (root when SSH is on)	root
A shell or IDE environment	root; the IDE runs as the login	root, or the user you choose (Log in as, Run as: `ssh.user`)

The login must exist in the image. An environment's login has its home on the drive, /content/home/<user>.

Setup#

A setup (spec.setup; Setup in the form; --pip, --apt and --setup-script on astra env create) installs what the image lacks before Jupyter, the SSH server or the IDE starts:

Part	Installed	When	Where
pip packages (`pip`)	`pip install --user` from a requirements list	At the first start, and again when the setup or the image changes	On the drive: a notebook's `/content/.hesperus/python`; an environment's `~/.local` in its home
System packages (`apt`)	With the image's package manager: apt, dnf or apk	At every start (they live in the container)	In the container; downloads are cached on the drive, so only the first start downloads them
Script (`script`)	Run with `sh`, as root, in `/content`	At the first start, and again when the setup or the image changes	What it writes under `/content` stays

At most 64 pip requirements (each at most 256 characters, no options such as -r or --index-url), 64 system packages (lowercase names, optionally =version) and a 16 KiB script. A preset adds its own first: huggingface its pinned Hugging Face packages, cuda its compilers and Python (Presets reference).

The setup's output is in the runtime's run log and in /content/.hesperus/env/<runtime>/setup.log on the drive. A failure is logged, never fatal: the runtime starts anyway, and the setup is tried again at the next start. The container must run as root to install system packages (presets and environments do).

Basic tools#

git, curl, htop and tmux — and nvtop when the runtime has GPUs — are installed in the background when the image lacks them, from the same cache. A package the image's manager does not have is noted on the drive and not tried again. Clear Basic tools (setup.tools: false, --no-tools) to leave the image as it is.

On every runtime#

nvidia-smi: a runtime with GPUs on an NVIDIA machine always has nvidia-smi and NVML, whatever the image says (NVIDIA_DRIVER_CAPABILITIES includes utility).
%pip install in a notebook puts packages on the drive, and the next cell imports them without a kernel restart (Install packages).
Spark (the spark preset) runs in local mode on the runtime's cores (spark.master local[<cores>]), its driver given 60% of the runtime's memory, its scratch space (SPARK_LOCAL_DIRS) on the drive; pyspark, spark-submit and spark-shell work as they are.
Credentials of the workspace can be given to a runtime as environment variables (spec.credentials, API only); the machine resolves them, as for any run (Credentials).