SSH into your runtime

Every running Neural Studio runtime accepts SSH from your own machine, so you can use ssh, scp, rsync, VS Code Remote-SSH, Cursor, or JetBrains Gateway against it exactly as you would against any cloud box. Nothing is exposed on the VM: the runtime only ever opens an outbound tunnel to the session gateway, and the ns CLI relays your SSH client through that tunnel. Key authentication stays end to end between your SSH client and the runtime's sshd; the platform authorizes which runtime you may reach and pipes bytes.

One-time setup

  1. Register your public key. Settings → SSH keys → Add key, and paste the contents of your ~/.ssh/id_ed25519.pub (or another supported type). The key is installed on every runtime in the workspaces you belong to, and pushed live to the ones already running.

  2. Install the CLI. pip install neural-studio provides the ns command.

  3. Create an API key. Settings → API keys → Create key (full access), then put it where the CLI looks for it:

    export NEURAL_STUDIO_API_KEY=ns_...
# or, persistently:
mkdir -p ~/.config/neural-studio
printf 'api_key = "ns_..."\n' > ~/.config/neural-studio/config.toml

    The CLI talks to the platform with this key; a runtime's own session key cannot be used to open SSH.

Connecting

Find the runtime id in the notebook's runtime bar (SSH → copy id, or the ssh-config block it shows). Then:

ns ssh-config --install <runtime-id>
ssh ns-<runtime-id>

ns ssh-config --install writes a fenced Host ns-<runtime-id> block into ~/.ssh/config whose ProxyCommand is ns ssh --stdio <runtime-id>. Re-running it replaces the block in place. The login user is user (the same account your notebook kernel and terminal run as); the CLI fills it in from the API, and --user overrides it if you ever need to.

ns ssh <runtime-id> [ssh args...] is a shortcut for ssh ns-<runtime-id>.

Host keys are recorded in ~/.ssh/known_hosts.neural-studio on first connect (StrictHostKeyChecking accept-new). Every runtime is a fresh VM, so a new runtime under the same id will present a new host key; delete the old line from that file if ssh complains.

Files

scp and rsync work unmodified once the config block is installed:

scp ./data.parquet ns-<runtime-id>:~/workspace/
rsync -av --progress ./project/ ns-<runtime-id>:~/workspace/project/

~/workspace on the runtime is your durable workspace filesystem — anything you copy there survives the runtime stopping. The rest of the home directory does not.

VS Code Remote-SSH

  1. Install the Remote - SSH extension.
  2. Run Remote-SSH: Connect to Host… and pick ns-<runtime-id> (it appears automatically once the config block is installed).
  3. Open the folder /home/user/workspace.

VS Code installs its server under ~/.vscode-server on the runtime; that directory is not durable, so the first connect to a new runtime downloads it again.

Cursor and JetBrains Gateway

Cursor uses the same Remote-SSH flow as VS Code (Connect to Host… → ns-<runtime-id>). JetBrains Gateway: New connection → SSH → host ns-<runtime-id> (the ProxyCommand in ~/.ssh/config is honoured), then open /home/user/workspace.

Revoking a key

Settings → SSH keys → Revoke. The key is removed from every running runtime within seconds, and never installed on a new one. Rotating a key (replace the public key in place) behaves the same way: the old key stops working, the new one starts working, on running runtimes immediately.

Troubleshooting

  • ns: gateway rejected the SSH relay upgrade — the runtime is not running with a connected tunnel (it is still starting, or has stopped), or the ticket was refused. Check the runtime's status in the app and retry.
  • Permission denied (publickey) — your key is not registered, was revoked, or ssh is offering a different key. ssh -v ns-<runtime-id> shows which keys were tried; -i ~/.ssh/id_ed25519 pins one.
  • ns: No API key found — set NEURAL_STUDIO_API_KEY or the config file as above. The ProxyCommand runs ns from your login shell's PATH, so the key must be visible to that shell, not only to a virtualenv.
  • ns: the session gateway host is not configured — the environment you are pointed at has no gateway; check NEURAL_STUDIO_API_URL.
  • You are not a member of the runtime's workspace — the API answers 404 for runtimes you cannot see; SSH is limited to workspaces you belong to.