CLI#

astra env manages development environments (runtimes of kind shell and ide), and astra ssh connects to any runtime with SSH. They work in the organisation, workspace and cluster you chose with astra use (Install the CLI). astra runs on Linux (amd64, arm64) and macOS (Apple silicon); astra ssh also needs OpenSSH's client (ssh) on your computer.

astra has no commands for notebooks, for the workspace's limits per person, or for credentials given to a runtime: use the console or the API for those.

$ astra login
$ astra use acme/vision@lab-a
$ astra env presets
$ astra env create dev --preset pytorch --gpus 1 --memory 32G
$ astra ssh dev
$ astra ssh config

astra env#

Command	Alias	Description
`create <name> [flags]`		Make an environment and start it.
`list`	`ls`	The workspace's environments (yours and the others').
`get <name>`		One: its state, why, its machine, and how to connect.
`start <name>`		Start it again (its drive kept its files).
`stop <name>`		Stop it: its GPUs are freed, its drive keeps its files.
`delete <name>`		Delete it. Its drive stays: delete that in the console.
`presets`		The presets `create --preset` takes, their builds and download sizes.
`open <name>`		Open an IDE environment's editor in your browser, starting it if it is stopped.
`share <name> <e-mail>`		Share it with a person of the workspace.
`unshare <name> <e-mail>`		Stop sharing it with someone.
`port <name> <port>`		Open an app running in it at an address of its own.

astra env create#

Flag	Default	Description
`<name>`	required	Lowercase letters, digits and `-`, starting with a letter, at most 40 characters.
`--kind <shell\\|ide>`	`shell`	`shell`: SSH only. `ide`: VS Code in the browser too (`astra env open`).
`--folder <PATH>`	your home on its drive	The folder an IDE opens. `--kind ide` only.
`--no-ssh`	off	An IDE without SSH (only the browser's editor). `--kind ide` only.
`--preset <ID>`	`python`	A preset (Presets). Not with `--image`.
`--image <REF>`		An image of your own instead (any with `/bin/sh`; for an IDE, built on glibc).
`--pip <REQ>`		Setup: a pip requirement installed once onto its drive. Repeatable.
`--apt <PKG>`		Setup: a package of the image's package manager (apt, dnf, apk), installed at each start from a cache on the drive. Repeatable.
`--setup-script <FILE>`		Setup: a shell script (a file on your computer) run once, as root, in `/content`.
`--no-tools`	off	Leave the image as it is: no git, curl, htop, tmux, nvtop added.
`--cpu <N>`	`2`	CPU cores.
`--memory <SIZE>`	`4G`	Memory: `16G`, `512M`, `1T` (also `16Gi`); a plain number is MiB.
`--gpus <N>`	none	GPUs. `--gpu-memory` or `--gpu-model` alone ask for 1.
`--gpu-memory <GB>`	any	Only GPUs with at least this much memory each.
`--gpu-model <MODEL>`	any	Only GPUs whose model contains this. Repeatable.
`--machine <NAME>`	any	On this machine.
`--pool <NAME>`	any	On a machine of this pool.
`--home-drive <DRIVE>`	`<name>-home`, made now	Its home and projects at `/content`: an existing drive of the workspace.
`--drive <DRIVE>:<PATH>[:ro\\|:rw]`		Another drive too, at an absolute path (read-write unless `:ro`). Repeatable.
`--idle <MINUTES>`	`60`	Stopped after this many minutes with nobody connected: 5 to 1440. `0`: never — workspace admins only.
`--user <USER>`	`root`	Log in as (a user of the image). An IDE runs as this user.
`--for <E-MAIL>`	you	Make it for someone else: it is theirs. Workspace admins only.
`--share <E-MAIL>`		Share it with a person of the workspace. Repeatable.
`--app <NAME>=<PORT>` or `--app <PORT>`		An app it serves, listed with an Open button (`tensorboard=6006`). Repeatable.

An e-mail must be a member of the workspace, or an owner or admin of its organisation; otherwise: [email protected] is not a member of workspace vision: add them in the console (Settings → Members) first.

$ astra env create dev --preset pytorch --gpus 1 --gpu-memory 24 --memory 32G --pip einops==0.8.1
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
code is pending: `astra env open code` opens its editor in your browser, `astra ssh code` a terminal

With --for, it first prints bens is [email protected]'s (made by you). --folder or --no-ssh without --kind ide is refused: --folder and --no-ssh are an IDE's (--kind ide); a shell environment is reached over SSH only.

astra env list#

$ astra env list
NAME  KIND   STATE    MACHINE  GPUS  USER  IDLE STOP             OWNER
code  ide    Stopped  gpu-01   1     root  -                     user:7c1e2f4a-…
dev   shell  Ready    gpu-01   1     root  2026-10-02T11:42:10Z  user:7c1e2f4a-…

Runtimes of kind shell and ide only; a notebook's runtime is not listed (the console's Hesperus → Runtimes lists every runtime). With none: No environments: astra env create <name> --gpus 1.

astra env get#

$ astra env get dev
dev: Ready — Ready on gpu-01 (1 × NVIDIA GeForce RTX 4090)
machine: gpu-01
image:   pytorch/pytorch:2.14.1-cuda12.6-cudnn9-runtime@sha256:1262abc8…
drive:   dev-home (home /content/home/root)
idle:    stopped after 60 min with nobody connected
connect: astra ssh dev   (or `astra ssh config`, then VS Code / Cursor: Remote-SSH)
owner:   [email protected]

An IDE environment adds ide: astra env open <name> with its console address and the folder it opens; a shared one adds shared:, and each named app a line app: <name> — astra env port <env> <port>.

astra env start, stop, delete#

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

Starting one that is Stopping is refused until it has stopped. Over a limit of the workspace, starting is refused with HESPERUS_LIMIT (Limits and errors).

astra env presets#

$ astra env presets
ID                NAME                          BUILDS (download)           WHAT
python (default)  Python + SciPy                cpu 1.3 GB                  Python 3.13 with NumPy, pandas, …
python-3.12       Python 3.12                   cpu 381 MB                  Plain Python 3.12 on Debian 12 …
pytorch           PyTorch                       nvidia 4.0 GB, amd 20.5 GB  PyTorch 2.14 with CUDA 12.6 …
…

astra env create <name> --preset <id> [--gpus 1]: the NVIDIA or AMD build is chosen for the machine's GPUs.

astra env open#

Argument or flag	Description
`<name>`	An environment of kind `ide`.
`--print`	Only print the address; open no browser.

It starts a stopped (or failed) environment — code was stopped: starting it (the page waits until its editor is ready) — then opens the console's page for its editor, which waits until it is ready and goes to the editor's own address. You must be signed in to the console in that browser. On a shell environment: dev has no browser IDE (it is a shell runtime): astra ssh dev, or make one with astra env create <name> --kind ide.

$ astra env open code --print
https://console.astralyx.cloud/o/acme/w/vision/environments/lab-a/code/ide

$ astra env share dev [email protected]
dev is shared with [email protected]: `astra ssh dev` from their computer
$ astra env unshare dev [email protected]
dev is no longer shared with [email protected]: their next connection is refused (one already open runs until it closes)

Its owner and workspace admins share it. Sharing with its owner is refused (dev is [email protected]'s already); unsharing someone it is not shared with too (dev is not shared with [email protected]).

astra env port#

Argument or flag	Description
`<name>`	The environment, or any runtime you may use.
`<port>`	The app's port in the container. Not 2222, nor the runtime's own server's (8888 in a notebook's runtime, 8822 in an IDE).
`--as <NAME>`	Remember it on the runtime under this name (the console lists it with an Open button).
`--print`	Only print the address; open no browser.

The runtime must be on a machine (Starting or Ready). The address works once, within a minute, and signs the browser that opens it in to that app only, for 8 hours.

$ astra env port dev 6006 --as TensorBoard --print
https://r-4f1c9a0b2d7e83a65c10-6006.<runtime domain>/__astralyx/enter?ticket=…
(works once, within a minute: it signs the browser that opens it in to https://r-4f1c9a0b2d7e83a65c10-6006.<runtime domain> only)

Without --print it opens your browser and prints Opened <address>.

astra ssh#

astra ssh <name> makes an Ed25519 key on your computer the first time, has the workspace's certificate authority sign it for that runtime (valid 8 hours), and runs your ssh with astra ssh --proxy as its ProxyCommand. A stopped runtime is started first, and astra waits up to 15 minutes for it to be ready.

Argument or flag	Default	Description
`<name>`	required	An environment, or a notebook's runtime with SSH on.
`-l`, `--user <USER>`	the runtime's user	Log in as another user of the image.
`--no-start`	off	Do not start a stopped runtime: dev is stopped: astra env start dev.
`-- <command>…`	a shell	Run this command instead of a shell; the exit status is its own.
`--proxy <HOST>`		Be ssh's `ProxyCommand` for a host `astra ssh config` wrote. Not with a name.
`--refresh <HOST>`		Renew HOST's certificate if it is about to expire; quiet. Used by the `~/.ssh/config` block.

$ astra ssh dev -- nvidia-smi --query-gpu=name,memory.total --format=csv
astra: starting dev…
astra: dev is pending: Started again by user:7c1e2f4a-…
astra: dev is starting: Starting its SSH server on gpu-01 (1 × NVIDIA GeForce RTX 4090)
name, memory.total [MiB]
NVIDIA GeForce RTX 4090, 24564 MiB

Messages:

Message	Meaning
`astra: starting dev…`	It was stopped or failed; `astra` starts it.
`astra: dev is pending: …`, `astra: dev is starting: …`	Waiting, with the runtime's reason.
`dev was not ready in 15 minutes`	Still not ready: look at Why? on its page.
`dev has no SSH (turn it on, or use an environment: astra env create)`	A notebook's runtime without SSH.
`which environment? \`astra ssh ` (see `astra env list`)`	No name given.
`ssh: … (is OpenSSH's client installed?)`	No `ssh` on your computer.
`a certificate for dev: …` with runtime dev is user:…'s: only its owner, the people it is shared with and the workspace's admins may connect to it	Not yours, not shared with you.

astra ssh config#

Writes a Host for each runtime you own that has SSH into a marked block of ~/.ssh/config, replaced each time (and put first when there was none, so a Host * below does not override it). Environments shared with you are not included: connect to them with astra ssh <name>. Run it again after making another environment.

Flag	Default	Description
`--print`	off	Print the block instead of writing it.
`--file <PATH>`	`~/.ssh/config`	The file.

$ astra ssh config
/home/ana/.ssh/config: dev.lab-a.vision.acme.astra, code.lab-a.vision.acme.astra
Connect with `ssh dev.lab-a.vision.acme.astra`, or open it in VS Code or Cursor (Remote-SSH).

With none: No runtime of yours has SSH in acme/vision: astra env create <name>.

A host is <runtime>.<cluster>.<workspace>.<org>.astra. The block for one host:

~/.ssh/config

# >>> astra ssh: written by `astra ssh config`; changes inside are replaced >>>
Match originalhost dev.lab-a.vision.acme.astra exec "/home/ana/.local/bin/astra ssh --refresh %n"
Host dev.lab-a.vision.acme.astra
  User root
  ProxyCommand /home/ana/.local/bin/astra ssh --proxy %n
  IdentityFile "/home/ana/.config/astra/ssh/dev.lab-a.vision.acme.astra/id_ed25519"
  CertificateFile "/home/ana/.config/astra/ssh/dev.lab-a.vision.acme.astra/id_ed25519-cert.pub"
  IdentitiesOnly yes
  HostKeyAlias dev.lab-a.vision.acme.astra
  UserKnownHostsFile "/home/ana/.config/astra/ssh/known_hosts"
  StrictHostKeyChecking accept-new
  ServerAliveInterval 30
# <<< astra ssh <<<

ssh reads the certificate before it runs the ProxyCommand, so the Match … exec line renews a certificate with less than 10 minutes left while ssh reads its configuration.

Files#

Under ~/.config/astra/ssh/ ($XDG_CONFIG_HOME/astra/ssh/), readable by you only:

File	What
`<host>/id_ed25519`, `<host>/id_ed25519.pub`	The key for that runtime. The private key never leaves your computer.
`<host>/id_ed25519-cert.pub`	Its certificate, valid 8 hours; renewed when less than 10 minutes are left.
`<host>/meta.json`	The login user and when the certificate ends.
`known_hosts`	The runtimes' host keys. A runtime keeps its host key on its drive, so it is the same after a restart.