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. SSH needs the editor or owner role in the runtime's workspace (see Workspaces and members). 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; up to 10 active keys). The key is installed on every runtime in the workspaces where you are an editor or owner, and pushed live to the ones already running. A viewer's key is never installed.

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

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

    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

Open Connect → SSH Access in the notebook's runtime bar. It shows the session id of the running runtime (a UUID; this is the id ns uses, not the rt-… label that web-port addresses carry), the ready-made ssh ns-<session-id> command, and a Copy / Download button for an ssh-config block. Then:

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

ns ssh-config --install writes a fenced Host ns-<session-id> block into ~/.ssh/config whose ProxyCommand is ns ssh --stdio <session-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. The block the app offers under SSH Access is the same thing; whichever you install, the ProxyCommand runs ns, so the CLI must be on your login shell's PATH.

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

With the CLI-installed block, host keys are recorded in ~/.ssh/known_hosts.neural-studio on first connect (StrictHostKeyChecking accept-new); the block copied from the app has no UserKnownHostsFile line, so ssh uses your default ~/.ssh/known_hosts. Every runtime is a fresh VM with a fresh session id and a fresh host key, so stale entries rarely collide; delete the old line if ssh ever complains.

Files

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

scp ./data.parquet ns-<session-id>:~/workspace/
rsync -av --progress ./project/ ns-<session-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-<session-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-<session-id>). JetBrains Gateway: New connection → SSH → host ns-<session-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, you are a viewer in that workspace (a viewer's key is never installed), or ssh is offering a different key. ssh -v ns-<session-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.
  • 404 for a runtime you can see in the app: the API answers 404 for runtimes you cannot reach over SSH. You need the editor or owner role in the runtime's workspace.