SynapsePraesidion
한국어English
Docs contents

Guides

Connecting over SSH (when allowed)

When an admin allows SSH, you connect to your running workspaces from your own terminal or desktop VS Code. Making and registering a key, the connect commands, and what to do when it fails.

App in development

On this page

The portal screens are in development. Their words and layout may still change; the commands behind the buttons are already built.

If an admin allows SSH for your account, you can reach your running workspaces from your own terminal, scp, sftp or desktop VS Code (Remote-SSH). It is the same workspace and the same user as the web IDE, so you can attach to tmux and screen sessions you started there.

Before you start

  • Allowed person by person. Without it, the SSH section of [My account] says “When an admin allows SSH, you register keys here.”
  • SSH means bulk download. With SSH you can copy files out of the workspace in bulk with scp or sftp, which is why it is off by default.
  • No password. “There is no password sign-in: only a registered key gets in.”
  • Your own workspaces, while they run. A key reaches only your own workspaces, and “It connects only while the workspace runs.”

What you need

  • OpenSSH 8.1 or later. Check with ssh -V. Up-to-date Windows 10 and 11, macOS and Linux have it; on an older Windows 10, update Windows.
  • cloudflared, only to connect from the internet.
  • Desktop VS Code with the Remote - SSH extension, only to connect with VS Code.

Set up this computer (once per computer)

The SSH section of [My account] lists the setup steps in order. Choose Windows (PowerShell), macOS or Linux under “This computer” and it shows that system's commands, copied with one press. The commands below are examples of what it shows.

  1. Open a terminal

    On Windows, open PowerShell from the Start menu (PowerShell, not Command Prompt). On macOS, open Terminal from Spotlight (Cmd+Space). On Linux, open a terminal. Paste every command below there.

  2. Make a key

    ssh-keygen -t ed25519

    Press Enter to save it in the default file. A passphrase is recommended on a laptop; press Enter twice for none. If it says the file exists, answer n and use that key, unless it was revoked (a password change revokes keys): then answer y to make a new one.

  3. Show the public key

    Windows (PowerShell)

    Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub

    macOS, Linux

    cat ~/.ssh/id_ed25519.pub

    Copy the whole line it prints; it starts with ssh-ed25519. Never paste the private key (id_ed25519, without .pub).

  4. Register the key

    In the SSH section of [My account], press [Add key] and paste the line under “Public key (the content of ~/.ssh/id_ed25519.pub)”. An account with an authenticator app needs a code from the last 10 minutes. If you paste a private key by mistake, the screen says so and registers nothing. Each person can register up to 10 keys by default.

  5. Install cloudflared (internet only, once)

    Windows (PowerShell)

    winget install --id Cloudflare.cloudflared

    On macOS and Linux, copy and run the one-line command the screen shows; it downloads cloudflared from Cloudflare's GitHub releases and installs it. If it asks for a password, it is this computer's. Then open the terminal and VS Code again.

  6. Prepare VS Code (VS Code only, once)

    Install Remote - SSH (ms-vscode-remote.remote-ssh) from the Extensions view. Then, in Settings (Ctrl+, / Cmd+,), search Local Server Download and choose always, and search Download Extensions Locally and turn it on. If you edit settings.json yourself, add these lines:

    settings.json

    "remote.SSH.localServerDownload": "always",
"remote.downloadExtensionsLocally": true

    The workspace cannot download the VS Code server or its extensions itself, so this computer brings them.

Registering a key shows this in the console under the screen:

Command console App in development
synapse ssh-key add --name laptop Done 
stdin: (hidden)Added SSH key: k-7d1f9e24 (laptop, SHA256:EAHucGguNs+B+u0EKvEBqdDNQsKyB42UfiCebb80fck)It reaches your active workspaces while they run and SSH is allowed. How to connect: synapse ssh guide
This is an example, drawn from the app in development.

Connecting

While a workspace is “Running”, the connect commands appear under “Connect over SSH” on the workspace and under “Connect” in the SSH section of [My account]. The server builds them for this installation, and a press copies them. Until you register a key, they are dimmed.

Two tabs choose the network: “Office network” and “Internet”. On a laptop that goes between the office and home, use the Internet lines: they work in the office too.

The commands below show the shape only. Addresses and ports differ between installations, so copy the ones on the screen.

From the office network

Terminal

ssh -a -x -J jump@198.51.100.10:2222 researcher@ws-0012

From the internet

First run this, and keep it running:

Run this and keep it running

cloudflared access tcp --hostname ssh.example.org --url 127.0.0.1:2022

Then, in another terminal:

Then, in another terminal

ssh -a -x -J jump@127.0.0.1:2022 researcher@ws-0012

The short command and VS Code

Paste the settings lines from the screen once at the top of your SSH settings file, and from then on a short command connects. Keep the lines of one network per computer. The file is %USERPROFILE%\.ssh\config on Windows and ~/.ssh/config on macOS and Linux; the screen has a command that opens it.

~/.ssh/config (Internet, example)

# Synapse (app.example.org) from the internet, through Cloudflare
Host ws-*
  User researcher
  ProxyCommand ssh -o StrictHostKeyChecking=accept-new -o "ProxyCommand=cloudflared access ssh --hostname ssh.example.org" -W %h:%p jump@ssh.example.org
  StrictHostKeyChecking accept-new
  ForwardAgent no
  ForwardX11 no
  ServerAliveInterval 30

These lines apply to every host whose name starts with ws-. Do not create this file with > or Set-Content in PowerShell: OpenSSH cannot read the encoding they write.

After that, connect like this in a terminal. In VS Code, choose Remote-SSH: Connect to Host... and enter ws-0012.

ssh ws-0012

The first connection

The one-line command asks on the first connection whether to trust a host key, twice: for the entrance and for the workspace. If it matches “Fingerprints to check on the first connection” on the screen, type yes. With the settings lines in place (VS Code included), new host keys are accepted without asking; to check them, compare the fingerprints on the screen after the first connection.

If it fails

What OpenSSH prints (in English), and what it means. The screen's “If it fails” lists the ones for the network you chose.

If you seeWhat it means and what to do
Permission denied (publickey)No key of this computer is registered to your account: register one in My account. Keys stop working when SSH is withdrawn or the account is disabled, and a password change revokes them.
open failed: connect failed: Connection refusedThe workspace has just started and SSH is not up yet. Wait half a minute and try again.
Temporary failure in name resolutionThe workspace is not running. Start it, then try again.
administratively prohibitedNot one of your workspaces, or not an active one.
connect to host (entrance address) port 2222: Connection refusedOffice network: the SSH entrance is not running. Tell an admin.
Connection timed out, Operation timed out, No route to host, Network is unreachableOffice network: this computer is not on the office network. Use the Internet lines.
connect to host 127.0.0.1 port 2022: Connection refusedInternet: the first step, cloudflared, is not running. Start it in another terminal and keep it open.
cloudflared: command not found, 'cloudflared' is not recognizedInternet: cloudflared is not installed, or this terminal or VS Code was open before it was. Install it, then open them again.
Connection closed by 127.0.0.1 port 2022, kex_exchange_identification, websocket: bad handshakeInternet: the connection through Cloudflare did not reach the SSH entrance. Try again in a minute; if it keeps failing, tell an admin.
Could not resolve hostname ws-The short command works only with the SSH settings lines in place. Add them, or use the one-line command.
Too many authentication failuresThis computer offered too many other keys first. Remove them from the SSH agent with ssh-add -D (the key files stay), then try again.
REMOTE HOST IDENTIFICATION HAS CHANGEDDo not connect. Tell an admin.

Revoking a key

You can revoke a key in the SSH section of [My account]. A revoked key cannot open new connections, and the same key cannot be registered again. Connections already open end when the workspace stops, or within about two minutes if it was your last key. A password change revokes all your keys unless you choose “Keep my API tokens and SSH keys”.