Skip to content

Use ssh, scp and rsync#

SSH goes into the runtime's container — never the machine — through the machine's own outbound connection: no port is opened anywhere. astra ssh gets a certificate for you and runs your system's ssh; after astra ssh config, every tool that speaks SSH connects by host name. How it works is in SSH access and certificates.

Before you begin#

  • An environment, or a notebook's runtime with SSH on (below).
  • To be its owner, one of the people it is shared with, or an admin of the workspace. Other editors are refused (403 SSH_FORBIDDEN); viewers reach no runtime.
  • astra on your computer (Linux or macOS), signed in and working in the runtime's workspace and cluster (Install the CLI), and OpenSSH's client (ssh, scp; rsync for rsync).

Open a shell#

$ astra ssh dev

astra ssh makes an Ed25519 key on your computer the first time (in ~/.config/astra/ssh/<host>/; the private key never leaves it), has the workspace's certificate authority sign it for this runtime — valid 8 hours, renewed when less than 10 minutes are left — and runs ssh with it. You land as the runtime's login user, in its home (an environment's is on its drive, /content/home/<user>).

A stopped runtime is started first, and astra waits for it, up to 15 minutes, saying what it waits for on standard error:

astra: starting dev…
astra: dev is pending: Started again by user:7c1e2f4a-93b0-4d51-a6f2-0e8d3b9c1a55
astra: dev is starting: Starting its SSH server on gpu-01 (1 × NVIDIA GeForce RTX 4090)
Flag Default Description
<name> required The environment, or any runtime with SSH.
-l, --user <USER> the runtime's login user Log in as another user of the image (the container runs as root when SSH is on).
--no-start off Do not start a stopped runtime: fail with dev is stopped: astra env start dev.
-- <command> [args…] a shell Run this command instead, and exit with its status.

Run one command#

$ astra ssh dev -- nvidia-smi --query-gpu=name,memory.total --format=csv
name, memory.total [MiB]
NVIDIA GeForce RTX 4090, 24564 MiB
$ astra ssh dev -- python -c "import torch; print(torch.cuda.is_available())"
True

A runtime with GPUs has nvidia-smi on NVIDIA machines whatever its image (Troubleshooting).

Copy files with scp and rsync#

scp, rsync, sftp and plain ssh connect by host name once astra ssh config has written the hosts of your runtimes. Below, dev.<cluster>.<workspace>.<org>.astra is the host it printed:

$ astra ssh config
$ export H=dev.<cluster>.<workspace>.<org>.astra
$ scp train.py $H:/content/projects/
$ rsync -az --progress ./data/ $H:/content/data/
$ rsync -az $H:/content/projects/runs/ ./runs/
$ ssh $H

Copy into /content (the drive): it is kept when the runtime stops. Anything elsewhere in the container is gone at the next start.

astra ssh config writes hosts only for runtimes you own. For one shared with you, use astra ssh <name>, and pipe files through it:

$ tar -cz ./data | astra ssh dev -- tar -xz -C /content
$ astra ssh dev -- tar -cz -C /content runs | tar -xz

Forward a port#

Local port forwarding is allowed (it is what editors' Remote-SSH uses), so a server in the container is reachable on your computer for as long as the connection is open. For TensorBoard on port 6006 in the container:

$ ssh -N -L 6006:127.0.0.1:6006 dev.<cluster>.<workspace>.<org>.astra

Then open http://localhost:6006. Agent forwarding is allowed too (ssh -A: git push with your own keys, which stay on your computer). Remote forwarding, X11 and tunnels are not. To open a server for your team in the browser instead, see Open a port as an app.

SSH into a notebook's runtime#

A notebook's runtime has no SSH unless you ask for it. With it, you get a terminal or an editor beside the notebook, on the same drive, as the notebook's user (jovyan in a Jupyter preset, so files match the notebook's; root otherwise).

Tick SSH into the runtime too in New notebook, Runtime settings or Change runtime… (a change starts a new runtime). The runtime then shows with SSH in Hesperus → Runtimes, and Connect opens its page with the commands.

astra has no notebook commands. Once the runtime has SSH, connect to it by its name (in Hesperus → Runtimes):

$ astra ssh mnist-3fa91c

Open the notebook with ssh on (it starts a runtime that has it):

$ curl -fsS -X POST "$API/notebooks/mnist/open" -H "Authorization: Bearer $ASTRAEUS_TOKEN" \
    -H 'content-type: application/json' -d '{"ssh": {"enabled": true}}' | jq '.runtime.ssh'
{
  "user": "root",
  "port": 2222,
  "home": "/root",
  "workdir": "/content"
}

mnist runs the PyTorch preset, which is not a Jupyter image, so the login is root; on a Jupyter preset it is jovyan, home /home/jovyan.

Or set spec.runtime_defaults.ssh on the notebook for every runtime it starts. ASTRAEUS_TOKEN and API are set as in Create and change a runtime.

Its home is in the container, not on the drive: keep your work in /content. A sandboxed runtime (isolation: sandbox) cannot have SSH.