Skip to content

Drives and home#

A runtime's container is new at every start. What you keep lives on drives: Astraeus drives of the workspace, on your machines' disks. This page explains which drive a runtime mounts at /content, what Hesperus keeps there, and how to mount other drives beside it.

The drive at /content#

Every runtime mounts one drive, read-write, at /content. It is what the notebook editor's Files panel shows, and where an environment's home is.

Runtime Its drive at /content Made
A notebook's The notebook's drive: by default the workspace's notebooks drive; or another drive chosen when the notebook was created (Drive in New notebook) notebooks on first use; another must exist
An environment (shell or IDE) Its own, <name>-home (dev-home for dev); or an existing drive given as spec.drive (--home-drive) <name>-home on first use

Both drives made by Hesperus are kept on each machine's data location: each machine that runs a runtime of the drive keeps its own copy, in a folder of its data location (<data location>/drives/<drive>/). Your notebooks and your home are files on your machine's disk; nothing of them passes through or stays in Astralyx. A machine needs a data location before such a runtime can run there (Choose where a machine keeps data).

One copy per machine

Copies are not synchronised between machines. A runtime that starts on another machine sees that machine's copy of the drive — your notebook or your home as you left them there, or empty. Astraeus prefers a machine that already holds a copy, but a busy machine does not stop the runtime from going elsewhere. Pin environments (and notebooks you want in one place) to a machine, or put the files on a drive every machine sees: a shared filesystem, given as the environment's home drive or chosen as the notebook's drive.

Deleting a runtime never deletes its drive. Deleting a notebook leaves its file on the drive. To delete an environment's home drive and every copy of it, delete the drive under Astraeus → Drives.

What is kept under /content#

Path What Kind
notebooks/<name>.ipynb A notebook's file, by default notebook
.hesperus/python/ What %pip install and the setup's pip packages installed: the kernel's user site notebook
home/<user>/ The login's home: dotfiles, shell history, ~/.local (pip --user and the setup's pip packages), editors' servers (.vscode-server, .cursor-server), the IDE's settings and extensions (.local/share/code-server) environment
.hesperus/env/<runtime>/ The setup's log (setup.log), its markers, the basic tools' log; Spark's configuration and scratch space every runtime
.hesperus/cache/ Downloaded system packages, shared by the drive's runtimes every runtime with packages
.hesperus/ssh/<runtime>/ The runtime's SSH host key, the same after every restart runtimes with SSH

Keep your projects anywhere under /content (an environment's home, or a folder beside it). Leave .hesperus alone: deleting its host key makes ssh warn that the host key changed; deleting its markers runs the setup again.

The first time an environment's home is made, the image's /etc/skel is copied into it and it is given to the login.

Other drives#

A runtime can mount up to 16 other drives of the workspace beside its own: datasets, model weights, checkpoints, a folder on one machine. In the runtime form, under Drives:

  • Attach a drive: choose a drive, where it is Mounted at (such as /data/checkpoints) and its Access (Read-write or Read-only).
  • New drive: a drive made when you save, On each machine's data location or A folder on one machine (a machine and its folder).

In the spec, each is {name, mount_path, mode} in spec.drives (--drive <drive>:<path>[:ro] on astra env create). The rules:

  • mount_path is absolute, without . or .., and neither /content nor inside it, nor a system directory: /, /bin, /boot, /dev, /etc, /lib, /lib64, /proc, /root, /run, /sbin, /sys, /tmp, /usr, /var or anything inside them.
  • No two mounts overlap, each drive is mounted once, and the runtime's own drive is not among them.
  • The drive exists in the workspace: drive weights does not exist: create it first.

Drives that Astralyx manages for you (such as notebooks) are not offered in the form. Mounting another drive in a notebook's runtime starts a new runtime (Add drive… in its menu).

A drive constrains where the runtime may run, as for any run: a drive on one machine is mounted over the network elsewhere, a shared filesystem only on machines that see it. Why? says so when that is why it waits.

On a Mac#

Machines on macOS do not run Hesperus runtimes: add a Linux machine.