Skip to content

An environment with SSH in 2 minutes#

In this page you create a development environment — a container on a GPU machine of your workspace that runs an SSH server — connect to it with ssh, run a command on its GPU, set up your editor, and stop it. Nothing is opened on the machine: astra ssh reaches the container through the connection the machine already keeps with Astralyx.

Before you begin#

  • A workspace with a cluster and a Linux machine with an NVIDIA or AMD GPU (see the Astraeus Quick start), with a data location: the environment's home is kept on the machine's disk. Open Machines → the machine and, under Data location, press Confirm.
  • The editor or admin role in the workspace.
  • astra on your computer (Linux or macOS), signed in and working in the workspace: astra login, then astra use <org>/<workspace> (Install the CLI).
  • OpenSSH's client, ssh, on your computer: astra ssh runs it.
  • Below, <org>, <workspace> and <cluster> stand for your organisation, workspace and cluster, gpu-01 for your machine's name (Machines lists it), and ast_pat_… for a personal API token (Account → API tokens, for the API tab).

1. Create the environment#

  1. Open Hesperus → Environments and press New environment.
  2. Kind: Shell. Name: dev. Leave Idle stop at 60 and Log in as empty (root).
  3. Under Environment, keep the PyTorch card. The form asks for 4 CPU cores, 16 GB of memory and 1 GPU.
  4. Under Machine, pick your machine (gpu-01). The environment's home is kept on the machine it runs on, so pinning it means you always find your files.
  5. Press Create and start. The environment's page opens.

$ astra env create dev --preset pytorch --cpu 4 --memory 16G --gpus 1 --machine gpu-01
dev is pending: `astra ssh dev` connects once it is ready (and waits for it)


$ export ASTRAEUS_TOKEN=ast_pat_…
$ export API="https://console.astralyx.cloud/api/v1/orgs/<org>/workspaces/<workspace>/clusters/<cluster>/api"
$ 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": 4, "memory_bytes": 17179869184, "gpus": {"count": 1}},
                  "placement": {"node": "gpu-01"}}}' \
    | jq '{state: .status.state, drive: .spec.drive, login: .ssh.user, home: .ssh.home}'
{
  "state": "Pending",
  "drive": "dev-home",
  "login": "root",
  "home": "/content/home/root"
}

It is Pending, then Starting — the first start on a machine pulls the image, 4.0 GB for PyTorch's NVIDIA build — then Ready. Its own drive, dev-home, is made for it and mounted at /content.

2. Run a command on its GPU#

$ astra ssh dev -- nvidia-smi -L
astra: dev is starting: Starting its SSH server on gpu-01 (1 × NVIDIA GeForce RTX 4090)
Warning: Permanently added 'dev.<cluster>.<workspace>.<org>.astra' (ED25519) to the list of known hosts.
GPU 0: NVIDIA GeForce RTX 4090 (UUID: GPU-5d1c…)

astra ssh waits for the environment to be ready (up to 15 minutes), gets a certificate valid 8 hours for this environment only, and runs your ssh through the machine's connection. The host key is the environment's own and stays the same after every restart, so the warning appears once. On a machine with AMD GPUs, run astra ssh dev -- python -c "import torch; print(torch.cuda.get_device_name(0))" instead.

3. Open a shell#

$ astra ssh dev
root@…:~# pwd
/content/home/root
root@…:~# python -c "import torch; print(torch.cuda.is_available())"
True

You land in your home on the environment's drive, /content/home/root: your dotfiles, shell history and projects stay there when the environment stops. Work under /content; what you put elsewhere in the container is gone at the next start. Press Ctrl+D to leave.

4. Open it in VS Code or Cursor#

Write a host for each of your environments into ~/.ssh/config, once (and again after you make another):

$ astra ssh config
/home/you/.ssh/config: dev.<cluster>.<workspace>.<org>.astra
Connect with `ssh dev.<cluster>.<workspace>.<org>.astra`, or open it in VS Code or Cursor (Remote-SSH).

Then, in VS Code or Cursor with the Remote - SSH extension, Connect to Host… and choose dev.<cluster>.<workspace>.<org>.astra, or press Open in VS Code or Open in Cursor under Connect on the environment's page. The editor installs its server inside the container the first time, which needs the container to reach the internet over HTTPS; it is kept in your home on the drive. See Connect VS Code, Cursor or JetBrains Gateway.

5. Stop it#

Press Stop on the environment's page. Its GPU is freed; its drive keeps your files.

$ astra env stop dev
dev is stopping


$ curl -fsS -X POST "$API/notebook-runtimes/dev/stop" -H "Authorization: Bearer $ASTRAEUS_TOKEN" | jq -r .status.state
Stopping

Left alone, it stops by itself after an hour with nobody connected. The next astra ssh dev (or the editor connecting) starts it again.

Next#