Skip to content

Connect VS Code, Cursor or JetBrains Gateway#

Your desktop editor can work inside an environment on the workspace's GPUs: files, terminals, the debugger and extensions run in the container, the window on your computer. Editors connect over SSH, by a host name that astra ssh config writes into your ~/.ssh/config. Nothing is opened on the machine: the connection goes through the machine's own outbound connection to Astralyx (SSH access and certificates).

Before you begin#

  • An environment (or a notebook's runtime with SSH on) that is yours: astra ssh config writes hosts for the runtimes you own only. For one shared with you, use astra ssh <name> (Use ssh, scp and rsync).
  • astra on your computer, signed in and working in the environment's workspace and cluster (astra use <org>/<workspace>@<cluster>; Install the CLI). astra runs on Linux and macOS.
  • OpenSSH's client (ssh) on your computer.
  • For VS Code, Microsoft's Remote - SSH extension. Cursor has its own.
  • The container must reach the internet over HTTPS: the editor installs its server inside it on first connect (from update.code.visualstudio.com for VS Code, Cursor's servers for Cursor; JetBrains' for Gateway).

1. Write the hosts#

Run once on your computer, and again after you make another environment:

$ 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).

It keeps a marked block in ~/.ssh/config, replaced each time (put first in the file when there was none, so a Host * above cannot override it). Each host is <runtime>.<cluster>.<workspace>.<org>.astra:

~/.ssh/config
# >>> astra ssh: written by `astra ssh config`; changes inside are replaced >>>
Match originalhost dev.<cluster>.<workspace>.<org>.astra exec "/home/you/.local/bin/astra ssh --refresh %n"
Host dev.<cluster>.<workspace>.<org>.astra
  User root
  ProxyCommand /home/you/.local/bin/astra ssh --proxy %n
  IdentityFile "/home/you/.config/astra/ssh/dev.<cluster>.<workspace>.<org>.astra/id_ed25519"
  CertificateFile "/home/you/.config/astra/ssh/dev.<cluster>.<workspace>.<org>.astra/id_ed25519-cert.pub"
  IdentitiesOnly yes
  HostKeyAlias dev.<cluster>.<workspace>.<org>.astra
  UserKnownHostsFile "/home/you/.config/astra/ssh/known_hosts"
  StrictHostKeyChecking accept-new
  ServerAliveInterval 30
# <<< astra ssh <<<
  • The ProxyCommand carries the connection: it starts the environment if it is stopped and waits for it (up to 15 minutes).
  • The Match … exec line renews the certificate (valid 8 hours) while ssh reads its configuration, when less than 10 minutes are left. Your editor never sees a password or a long-lived key.
  • --print prints the block instead of writing it; --file <path> writes another file.

2. Open it in your editor#

  1. On the environment's page (Hesperus → Environments → the environment), under Connect, press Open in VS Code. It opens vscode://vscode-remote/ssh-remote+<host>/content: the host, folder /content.
  2. Or in VS Code: Remote-SSH: Connect to Host… and pick the ….astra host, then File → Open Folder /content (or your home, /content/home/<user>).
  3. The first time, VS Code installs its server in the container. It is kept in your home on the drive, so it is installed once.
  1. On the environment's page, under Connect, press Open in Cursor (cursor://vscode-remote/ssh-remote+<host>/content).
  2. Or in Cursor: Remote-SSH: Connect to Host… and pick the host.
  3. The first time, Cursor installs its server in the container, from Cursor's servers; it is kept in your home on the drive.
  1. In Gateway, New Connection → SSH.
  2. Host: the ….astra host. Gateway reads ~/.ssh/config; choose OpenSSH as the authentication agent if it asks.
  3. Project: /content, or a folder under it.
  4. Choose the IDE to run in the container. Gateway downloads its backend into the container the first time.

What you get#

  • You land as the environment's login user (root unless it was created with another) in your home on its drive, /content/home/<user>: your dotfiles, shell history and the editor's server stay there between starts.
  • An open SSH connection counts as someone connected: the environment does not stop as idle while your editor is attached. Close the window when you are done, and it stops after its idle time.
  • Each connection is recorded as a session (who, from what, how long — never what was typed): see Sessions and audit.

In a notebook's runtime with SSH on, the login is the notebook's user (jovyan in a Jupyter preset, else root) and its home is in the container, not on the drive: the editor's server is installed again after each start. Keep your work under /content.

Troubleshooting#

Symptom Cause Fix
astra ssh config says No runtime of yours has SSH You own no runtime with SSH in this workspace and cluster, or astra works in another. astra whoami; astra use <org>/<workspace>@<cluster>; for one shared with you, astra ssh <name>.
The editor hangs at Downloading VS Code Server or Installing The container cannot reach the internet over HTTPS. Let the machine's network reach update.code.visualstudio.com (or Cursor's, JetBrains' servers), or use the IDE in the browser, which the machine brings.
Could not resolve hostname …astra The host is not in ~/.ssh/config (an environment made since, or not yours). Run astra ssh config again.
runtime dev is …'s: only its owner, the people it is shared with and the workspace's admins may connect to it (SSH_FORBIDDEN) Not yours, and not shared with you. Ask its owner to share it.

More in Troubleshooting.