Create and change a runtime#

A runtime is where your code runs: a container on a machine of the workspace, with the CPU cores, memory, GPUs, image and drives you ask for. A notebook gets its runtime when you open it; an environment is a runtime. This page shows how to make both, and how to change what they run on. What each field means is in Resources and machines and Presets and setup.

Before you begin#

The editor or admin role in the workspace. Viewers see notebooks and runtimes, and change nothing.
A workspace with a cluster and at least one machine (Add a machine).
For the CLI tabs, astra, signed in and working in your workspace (Install the CLI).
For the API tabs, a personal API token (Account → API tokens). Below, <org>, <workspace> and <cluster> stand for your organisation, workspace and cluster (as in the console's address), and ast_pat_… for your token:
```
$ export ASTRAEUS_TOKEN=ast_pat_…
$ export CONSOLE="https://console.astralyx.cloud/api/v1/orgs/<org>/workspaces/<workspace>"
$ export API="$CONSOLE/clusters/<cluster>/api"
```
Names in paths and bodies are local to the workspace: dev, not a namespace.

Create a notebook#

A notebook is a title, a drive and the path of an .ipynb file on it. Its runtime settings (runtime_defaults) say what its runtimes are made of; opening it starts a runtime with them.

ConsoleCLIAPI

Open Hesperus → Notebooks and press New notebook (or Import .ipynb to start from a file from Colab, Jupyter or GitHub).
Title, then Name (How the cluster and links name it: lowercase letters, digits and dashes, at most 40).
Drive: where the file is kept. A workspace with no drive yet makes one named notebooks, kept on the machine it runs on.
File on the drive: a path ending in .ipynb, such as notebooks/analysis.ipynb (Mounted at /content in the runtime).
Below, choose the runtime: CPU cores, Memory (with its unit, MB or GB), GPUs, GPU memory, at least, GPU model, Machine, the Image (a preset card or Custom image), Setup, Drives, and SSH into the runtime too.
Press Create and open (Import and open). The editor opens and connects once the runtime is ready.

astra has no notebook commands. Use the console or the API.

Create the notebook, then open it: open finds your active runtime that serves it as asked, or starts one.

$ curl -fsS -X POST "$API/notebooks" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    -H 'content-type: application/json' \
    -d '{"metadata": {"name": "mnist"}, "spec": {"title": "MNIST", "runtime_defaults": {"image": "pytorch", "resources": {"cpu_cores": 4, "memory_bytes": 17179869184, "gpus": {"count": 1}}}}}' \
    | jq -r '.spec.drive + ":" + .spec.path'
notebooks:notebooks/mnist.ipynb
$ curl -fsS -X POST "$API/notebooks/mnist/open" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    -H 'content-type: application/json' -d '{}' \
    | jq '{runtime: .runtime.metadata.name, state: .runtime.status.state, reused}'
{
  "runtime": "mnist-3fa91c",
  "state": "Pending",
  "reused": false
}

The file is made by whoever opens the notebook first. Without drive, the notebook uses the workspace's notebooks drive, made on first use; without path, notebooks/<name>.ipynb. Every field is in the runtime specification.

A runtime that has no machine yet is Pending: nothing you ask for is refused because no machine has it now. Why? beside it says what it waits for (Troubleshooting).

Switch a notebook to other resources#

A runtime runs with exactly what it was started with. To change the GPUs, memory, image, machine or drives, the notebook moves to a new runtime: the notebook is saved to its drive first, and anything in the kernel's memory is lost — run the cells again.

ConsoleCLIAPI

In the notebook's editor, open the runtime's menu (its name at the top) and choose Change runtime…. When the runtime is stopped, Change runtime… is next to Connect.
Change the fields. A machine list shows what each machine has free, and whether your ask fits now, waits or will never fit there.
Stop the current runtime (checked) frees its machine; unchecked, the old runtime stops on its own when idle.
Press Switch. The editor reconnects to the new runtime.

Under Or connect to one of your active runtimes, Connect moves the notebook to a runtime of yours already running on the same drive, without changing the notebook's settings.

astra has no notebook commands. Use the console or the API.

Open the notebook with what you want; what you give overrides its runtime settings for this runtime. new: true always starts a new runtime; runtime connects to one you name (started again if it is stopped).

$ curl -fsS -X POST "$API/notebooks/mnist/open" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    -H 'content-type: application/json' \
    -d '{"resources": {"cpu_cores": 8, "memory_bytes": 34359738368, "gpus": {"count": 2, "min_memory_gb": 24}}}' \
    | jq -r '.runtime.metadata.name'
mnist-8c02d4
$ curl -fsS -X POST "$API/notebook-runtimes/mnist-3fa91c/stop" -H "Authorization: Bearer $ASTRAEUS_TOKEN"

The old runtime keeps running until you stop it, or until it is idle.

Mount another drive#

In the runtime's menu, Add drive… (restarts the runtime) opens the same dialog on its Drives: Attach a drive adds one of the workspace's drives, with where it is Mounted at (such as /data/checkpoints) and its access (Read-write or Read-only); New drive makes one when you switch, On each machine's data location or A folder on one machine. A runtime mounts at most 16 other drives, each at an absolute path outside /content and outside the system's directories (/bin, /boot, /dev, /etc, /lib, /lib64, /proc, /root, /run, /sbin, /sys, /tmp, /usr, /var). See Drives and home.

Set a notebook's runtime settings#

The runtime settings are what the notebook's next runtimes are made of, for everyone who opens it. Saving them changes no running runtime.

ConsoleCLIAPI

In Hesperus → Notebooks, press Runtime settings on the notebook's row.
Change the fields and press Save. A runtime already running keeps running as it is: to move to these settings now, open the notebook and use Change runtime….

astra has no notebook commands. Use the console or the API.

PUT /notebooks/<name> takes the whole spec: read it, change it, send it back. A field left out takes its default (a path left out becomes notebooks/<name>.ipynb). Changing drive or path moves no file.

$ curl -fsS "$API/notebooks/mnist" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    | jq '{spec: (.spec | .runtime_defaults.resources.gpus = {"count": 1, "models": ["4090"]})}' > change.json
$ curl -fsS -X PUT "$API/notebooks/mnist" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    -H 'content-type: application/json' -d @change.json | jq '.spec.runtime_defaults.resources.gpus'
{
  "count": 1,
  "models": ["4090"]
}

Stop, start and delete a notebook's runtime#

ConsoleCLIAPI

In the editor's runtime menu, Stop the runtime (frees the GPU). Connect starts a runtime again for the notebook: your files are there, the kernel's memory is not.
Hesperus → Runtimes lists every runtime of the workspace, with its machine, GPU, image, resources and when it stops if idle: Stop, Start, and Delete for one that is stopped.
Deleting a notebook (Delete on its row, confirming its name) removes it from the list. Its file stays on the drive, and its runtimes run on until stopped or idle.

astra env stop, start and delete take any runtime's name, a notebook's included:

$ astra env stop mnist-3fa91c
mnist-3fa91c is stopping

POST $API/notebook-runtimes/<name>/stop, POST …/start, DELETE $API/notebook-runtimes/<name> (the drive keeps its files), DELETE $API/notebooks/<name>.

Create an environment#

An environment is a long-lived runtime you reach from your own terminal or editor (kind Shell), or from VS Code in the browser too (kind IDE). Its own drive, <name>-home, is mounted at /content and holds your home and projects.

ConsoleCLIAPI

Open Hesperus → Environments and press New environment.
Kind: Shell (SSH only: a terminal, or VS Code, Cursor and JetBrains on your computer over Remote-SSH) or IDE (VS Code in the browser (code-server), opened at an address of its own; SSH beside it unless you turn it off).
Name: lowercase letters, digits and dashes, starting with a letter, at most 40.
Idle stop: minutes with nobody connected, 5 to 1440 (default 60; 0, never, is for the workspace's admins).
Log in as (Run as for an IDE): a user of the image; empty: root.
For an IDE: Folder it opens (empty: your home on its drive, /content/home/<user>), and SSH too.
Share with: people of the workspace who may use it as you do (Share an environment).
The resources, Machine, Environment (the image: a preset or Custom image), Setup and Drives, as for a notebook. The form starts from the PyTorch preset with 4 cores, 16 GB and one GPU.
Press Create and start. Its page opens.

$ astra env create dev --preset pytorch --gpus 1 --gpu-memory 24 --cpu 8 --memory 32G --machine gpu-01
dev is pending: `astra ssh dev` connects once it is ready (and waits for it)
$ astra env create code --kind ide --preset pytorch --gpus 1 --machine gpu-01
code is pending: `astra env open code` opens its editor in your browser, `astra ssh code` a terminal

Every flag is in the CLI reference.

$ curl -fsS -X POST "$API/notebook-runtimes" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    -H 'content-type: application/json' \
    -d '{"metadata": {"name": "dev"}, "spec": {"kind": "shell", "image": "pytorch",
         "resources": {"cpu_cores": 8, "memory_bytes": 34359738368, "gpus": {"count": 1, "min_memory_gb": 24}},
         "placement": {"node": "gpu-01"}}}' \
    | jq '{state: .status.state, drive: .spec.drive, ssh}'
{
  "state": "Pending",
  "drive": "dev-home",
  "ssh": {"user": "root", "port": 2222, "home": "/content/home/root", "workdir": "/content"}
}

Pin an environment to a machine

The home drive <name>-home is kept on each machine's data location: one copy per machine that runs the environment. Started on another machine, it finds that machine's copy, not your files. Choose a Machine (--machine, placement.node) so it always comes back to the same one; Astraeus prefers a machine that already holds a copy, but does not promise it. To share files between machines, put them on a drive every machine reaches and mount it, or give --home-drive a drive of your own.

Start, stop and delete an environment#

Any editor of the workspace may stop, start or delete any runtime; only connecting to it (SSH, its IDE, its apps) is kept to its owner, the people it is shared with and the workspace's admins.

ConsoleCLIAPI

Hesperus → Environments lists them, stopped ones last: Open IDE, Connect, Stop (or Start). On an environment's page, Delete appears once it is stopped (Its drive and its files stay).

$ astra env stop dev
dev is stopping
$ astra env delete dev
Deleted dev (its drive stays)

astra env start dev starts a stopped one again (dev is pending); while it is still stopping, starting it is refused. astra ssh dev and astra env open code start a stopped environment themselves.

POST $API/notebook-runtimes/<name>/stop, POST …/start, DELETE $API/notebook-runtimes/<name>. Starting one that is still Stopping is refused (409 NOTEBOOK_CONFLICT: runtime dev is stopping; start it when it has stopped).

Stopping frees its GPUs; its drive keeps its files. Starting makes a new container on the same drive: your home and projects are there, processes and anything outside /content are not.

Change an environment#

An environment's image, resources, machine and drives cannot be changed in place. Delete it and create it again with the same name: the new one mounts the same home drive, <name>-home, with your files.

ConsoleCLIAPI

On the environment's page, press Stop, then Delete.
New environment with the same Name and what you want now.

$ astra env stop dev
dev is stopping
$ astra env delete dev
Deleted dev (its drive stays)
$ astra env create dev --preset pytorch --gpus 2 --memory 64G --machine gpu-01
dev is pending: `astra ssh dev` connects once it is ready (and waits for it)

DELETE $API/notebook-runtimes/dev, then POST $API/notebook-runtimes with the same metadata.name.

Who it is shared with and its named apps can be changed in place: Share an environment, Open a port as an app.

Create and change a runtime#

Before you begin#

Create a notebook#

Switch a notebook to other resources#

Mount another drive#

Set a notebook's runtime settings#

Stop, start and delete a notebook's runtime#

Create an environment#

Start, stop and delete an environment#

Change an environment#

Related#