Runtime and notebook specification

This page lists every field Hesperus takes and returns: runtimes (a notebook's Jupyter runtime, a shell environment, an ide environment), notebooks, the body that opens a notebook, and the workspace's limits per person. The console's forms and astra env create fill in the same fields; API has the routes.

Names in bodies are local to your workspace (dev, notebooks), as on every route below $API. Sizes are bytes; GB in a GPU ask is a decimal gigabyte, as a machine reports its GPUs.

Runtime

An IDE environment with one GPU

{
  "metadata": {"name": "code"},
  "spec": {
    "kind": "ide",
    "image": "pytorch",
    "resources": {"cpu_cores": 8, "memory_bytes": 34359738368, "gpus": {"count": 1, "min_memory_gb": 24}},
    "placement": {"node": "gpu-01"},
    "drives": [{"name": "weights", "mount_path": "/models", "mode": "ReadOnly"}],
    "idle_timeout_minutes": 120,
    "ssh": {"enabled": true, "user": "root"},
    "ide": {"folder": "/content/projects/app"},
    "setup": {"pip": ["einops==0.8.1"], "apt": ["ffmpeg"]},
    "members": ["user:3b0c…"],
    "apps": [{"name": "TensorBoard", "port": 6006}]
  }
}

Top level

Field	Type	Default	Description
metadata.name	string	required	Lowercase letters, digits and -, starting with a letter, not ending with -, at most 40 characters. Labels under astraeus.io are refused.
spec	object	{}	What it is.
for	string	the caller	Whose it is, as user:<id>: a workspace admin makes it for someone else. Only on create.

spec

Field	Type	Default	Description
kind	jupyter, shell or ide	jupyter	jupyter: a notebook's Jupyter Server. shell: a development environment running only an SSH server. ide: the same with VS Code in the browser (code-server).
image	string	python	A preset's id (Presets) or an image reference: letters, digits and ./:@_-, at most 512 characters, not starting with -, /, : or @.
resources	object	2 cores, 4 GiB, no GPU	What it asks of its machine.
placement	object	anywhere	One machine or a pool.
drive	string	jupyter: notebooks; shell, ide: <name>-home	The drive mounted read-write at /content. The two defaults are made on first use (kept on each machine's data location); any other drive must exist.
drives	list of drive mounts	[]	Other drives of the workspace mounted too. At most 16.
idle_timeout_minutes	integer	jupyter: 30; shell, ide: 60	Stopped after this long without activity: 5 to 1440. 0: never — workspace admins only.
isolation	standard or sandbox	standard	sandbox runs it under gVisor. Not with SSH, and not for an ide runtime. API only.
credentials	list of credential variables	[]	Credentials of the workspace given as environment variables, resolved on the machine. At most 32. API only.
ssh	object	jupyter: off; shell, ide: on	SSH into the container.
ide	object	ide only, filled in	What the browser IDE opens. Refused on another kind.
setup	object	none	What it installs beside its image.
members	list of strings	[]	People of the workspace it is shared with, as user:<id>: at most 50, each once; its owner is dropped from the list. Changed later with PUT /notebook-runtimes/{name}/members.
apps	list of apps	[]	Servers it runs that people open at their own address. At most 16. Changed later with PUT /notebook-runtimes/{name}/apps.
notebook	string	none	The notebook it was opened for. Set by opening a notebook; refused on shell and ide.
started_by	string	set by the cluster	Its owner, user:<id>: who made it, or whom an admin made it for. Read-only.
created_by	string	set by the cluster	Who made it, when an admin made it for someone else. Read-only.

A runtime's specification cannot be changed once it is made, except its members and apps. To change anything else, make another runtime (a notebook's Change runtime… does) or delete the environment and make it again with the same name: its home drive <name>-home is still there.

resources

Field	Type	Default	Description
cpu_cores	integer	2	1 to 256. It may use idle cores beyond them.
memory_bytes	integer	4294967296 (4 GiB)	512 MiB to 4 TiB. A hard limit.
gpus.count	integer	0	0 to 16.
gpus.models	list of strings	[] (any)	Only GPUs whose model contains one of these, ignoring case (4090, H100). At most 8, each at most 64 characters. Needs count > 0.
gpus.min_memory_gb	integer	0 (any)	Only GPUs with at least this much memory each, in GB: 0 to 1024. Needs count > 0.

With GPUs and a preset, the preset's build for the machines' GPU vendor is chosen, and the GPUs are asked of that vendor only (Presets).

placement

Field	Type	Default	Description
node	string	none	This machine only. Letters, digits and -_., at most 63 characters.
pool	string	none	Machines of this pool only (their pool label). Same characters.

An empty placement ({}) is no placement: wherever there is room.

Drive mounts

Field	Type	Default	Description
name	string	required	A drive of the workspace. It must exist, and must not be the runtime's own drive. Each drive once.
mount_path	string	required	An absolute path without . or .., at most 512 characters. Not /content nor inside it, not /, and not a system directory or inside one: /bin, /boot, /dev, /etc, /lib, /lib64, /proc, /root, /run, /sbin, /sys, /tmp, /usr, /var. Mount paths may not overlap.
mode	ReadWrite or ReadOnly	ReadWrite

Credentials

Field	Type	Default	Description
credential	string	required	A credential of the workspace.
key	string	required	Its key: at most 253 characters, no /.
env	string	required	The variable: [A-Z_][A-Z0-9_]*, at most 128 characters, each once. Not one the runtime uses itself: JUPYTER_TOKEN, anything starting HESPERUS_, ASTRAEUS_, JUPYTER_ or DOCKER_STACKS_, nor CHOWN_EXTRA, CHOWN_EXTRA_OPTS, NB_UID, NB_GID, NB_USER, HOME, PATH, PIP_USER, PYTHONUSERBASE, PYTHONSTARTUP, PIP_BREAK_SYSTEM_PACKAGES, NVIDIA_DRIVER_CAPABILITIES, SPARK_LOCAL_DIRS, SPARK_CONF_DIR, PYSPARK_SUBMIT_ARGS.

ssh

Field	Type	Default	Description
enabled	boolean	the kind's: on for shell and ide, off for jupyter	A shell runtime's SSH cannot be off.
user	string	jovyan for a jupyter runtime of a Jupyter Docker Stacks preset (python, minimal, datascience, pytorch-cuda, tensorflow-cuda); else root	Who logs in. It must exist in the image. Lowercase letters, digits, _ and -, starting with a letter or _, at most 32 characters. An ide runtime's editor runs as this user even with SSH off.

SSH needs standard isolation.

ide

Field	Type	Default	Description
folder	string	the login's home, /content/home/<user>	The folder the IDE opens: an absolute path without .., ", ` or $. Made at start when missing.

setup

Field	Type	Default	Description
pip	list of strings	[]	pip requirements (transformers==5.18.0, git+https://…), installed with pip install --user onto the drive. At most 64, each at most 256 characters; no options (-e, -r, --index-url), comments or backslashes.
apt	list of strings	[]	Packages of the image's package manager (apt, dnf, microdnf, yum or apk), optionally =version. Entries are split on spaces; duplicates are dropped. At most 64, each at most 128 characters: lowercase letters, digits and +.-_.
script	string	none	A script run with sh, as root, in /content. At most 16 KiB, no NUL.
tools	boolean	true	Install git, curl, htop, tmux (and nvtop with GPUs) when the image lacks them.

A preset's own packages come first (the huggingface preset's pinned Hugging Face stack, the cuda preset's build tools). The pip part and the script run once, and again when the setup or the image changes; the packages live in the container and are installed at every start, from a cache on the drive. A failure is logged — in the run's log and in /content/.hesperus/env/<runtime>/setup.log — and never stops the runtime.

apps

Field	Type	Default	Description
port	integer	required	1 to 65535, each once. Not 2222 (SSH), not 8888 in a jupyter runtime (Jupyter), not 8822 in an ide runtime (the IDE).
name	string	port <n>	How it is listed: at most 40 characters.

Runtime as served

GET /notebook-runtimes/{name} (and each item of the list) returns metadata, spec as checked (defaults filled in), and:

Field	Type	Description
image_ref	string	The image it runs: a preset resolved to its pinned reference, for the build its run got.
status.state	string	Pending, Starting, Ready, Stopping, Stopped or Failed.
status.reason	string	Why, for people: Started by user:… (kept while Pending), Ready on gpu-01 (1 × NVIDIA GeForce RTX 4090), Stopped after 60 minutes idle.
status.created_at, status.updated_at	time	When it was made; when its state last changed.
status.finished_at	time	When it last went to Failed; cleared when it is started again.
status.run	string	Its current (or last) run: <name>-<generation>.
status.task	string	That run's worker: <name>-<generation>-0.
status.generation	integer	How many runs it has had; each start adds one.
status.node	string	The machine it is (or was last) on.
status.gpu	{count, models, ids}	Its GPUs, as the machine reports them.
status.ready	boolean	Whether its server answers now.
status.ready_at	time	When this run became ready.
status.last_activity_at	time	The last activity, as its machine reports it.
status.idle_stop_at	time	While Ready: when it stops if nothing happens before. Absent for a runtime that never stops when idle.
status.stopped_at	time	When its last run stopped or failed.
status.proxy_path	string	Where the console reaches its Jupyter Server (an ide runtime's editor), while Starting or Ready. Absent for shell.
ssh	object	How it is reached over SSH, when SSH is on.

SSH access

Field	Type	Description
user	string	Who logs in.
port	integer	2222, on the container's own loopback.
tcp_path	string	The raw TCP path to it, while it is on a machine (/v1/interactive/<task>/tcp/2222).
home	string	Where a login lands: /content/home/<user> in an environment (on its drive); /root or /home/<user> in a notebook's runtime (in the container).
workdir	string	/content.

Notebook

A notebook

{
  "metadata": {"name": "mnist"},
  "spec": {
    "title": "MNIST experiments",
    "drive": "notebooks",
    "path": "notebooks/mnist.ipynb",
    "runtime_defaults": {
      "image": "pytorch",
      "resources": {"cpu_cores": 4, "memory_bytes": 17179869184, "gpus": {"count": 1}},
      "placement": {"node": "gpu-01"}
    }
  }
}

Field	Type	Default	Description
metadata.name	string	required	As a runtime's: at most 40 characters.
spec.title	string	the name	At most 200 characters.
spec.description	string	none	At most 2000 characters.
spec.drive	string	notebooks (made on first use)	The drive its file is on. Any other drive must exist.
spec.path	string	notebooks/<name>.ipynb	The file, relative to the drive: ends in .ipynb, no .. or empty segments, at most 1024 characters. Changing drive or path later moves nothing.
spec.runtime_defaults	object	the python preset, 2 cores, 4 GiB	What its runtimes are made of unless the opener asks otherwise.

Served with created_by, created_at and status: last_runtime, last_opened_by, last_opened_at. The notebook's cells and outputs are in the .ipynb file on the drive, never in this object. Deleting a notebook removes the object only: the file stays, and its runtimes run on until stopped or idle.

runtime_defaults

Field	Type	Default	Description
image	string	python	As a runtime's image.
resources	object	2 cores, 4 GiB
placement	object	anywhere
drives	list of drive mounts	[]
ssh	object	off	SSH into its runtimes too.
setup	object	none

Opening a notebook

POST /notebooks/{name}/open takes an optional body; what it gives overrides the notebook's runtime_defaults for this opening:

Field	Type	Description
image, resources, placement, ssh, setup	as above	placement: {}: anywhere, whatever the defaults say.
drives	list	[]: no other drive, whatever the defaults say.
idle_timeout_minutes	integer	As a runtime's; 0 is an admin's.
isolation	string	standard or sandbox.
credentials	list	Credential variables.
runtime	string	Use this runtime (started again when stopped). It must serve the notebook's drive.
new	boolean	Make a new runtime even when one would do.

Without runtime or new, it finds your active runtime that serves the same drive, drives, image, resources, placement, isolation, credentials, SSH and setup; else starts your stopped one for this notebook again; else makes one named <notebook>-<6 hex digits>. The answer is {notebook, runtime, reused} (reused: false when it made or started one).

Limits per person

/notebook-limits/default: one object per workspace. Everyone reads it; workspace admins set it.

Field	Type	Default	Description
max_environments_per_person	integer	0 (no limit)	Environments (shell, ide) a person may have running at once: at most 1000.
max_gpus_per_person	integer	0 (no limit)	GPUs a person's runtimes, environments and notebooks' together, may hold at once: at most 10000.
updated_by, updated_at		read-only	Who set them, and when.

They are checked against the owner's runtimes that are Pending, Starting or Ready when a runtime is made or started, a notebook opened included. See Set per-person limits.

Related

• Presets
• API
• Limits and errors
• CLI
• Runtimes and kinds