How to Set Up an SSH Connection (Updated March 6, 2026) – Matlantis Corporation

This feature is only available when an admin user enables SSH access for a user under Dashboard > Users. It is currently offered as an experimental version. It utilizes the free open-source software called websocat, which enables WebSocket connections from the command line.

Setting Up Matlantis
Setting Up the Client
- For Windows
- For Mac/Linux
Configuring VSCode (Optional)
Configuring WinSCP (Optional, Windows only)
How to Configure the SSH Connection setting (Dashboard > Users, admin only)

Change log

Updated for security enhancements: The contents of the downloadable connection files (ssh_matlantis.sh, ssh_matlantis.bat) have been updated. (Mar. 6, 2026)
The file will now be downloaded when you click the URL.(Apr. 1, 2025)
- https://redirect.matlantis.com/api/me/ssh?script_type=bat (Windows, ssh_matlantis.bat)
- https://redirect.matlantis.com/api/me/ssh (Mac, ssh_matlantis.ssh)
It is now possible to grant permissions on a tenant basis, rather than on a per-user basis. (Apr. 2, 2025)
Updated ssh_matlantis.bat to automatically download the websocat executable. (Apr. 14, 2025)
We no longer need to be involved; admin users can now allow SSH connections by configuring the settings themselves. (Sep. 10, 2025)

-----

Setting Up Matlantis

The SSH connection setup environment is ready when /tmp/sshd.pid and ~/.ssh/environment exist. If they do not exist, please restart Matlantis.

Example: Execute the following command in /home/jovyan to check if sshd.pid exists.

ls /tmp

Return to Top⏎

Setting Up the Client

The process differs between Windows and Mac/Linux. Please follow the instructions based on your operating system.

For Windows
For Mac/Linux

Return to Top⏎

For Windows

1. Verifying SSH Functionality and Generationg Private and Public Key

Check if "ssh.exe" can be used in PowerShell. First, change to the "$HOME" directory, and then verify the version. if the version displayed, it is working correctly.
```
cd $HOME
ssh.exe -V
```
Generate a private and public key using "ssh-keygen"

Example: Using RSA (default) with 4096 bits (no passphrase is recommended if using VSCode)
```
ssh-keygen.exe -t rsa -b 4096
```

2. Uploading Public Key

Save the generated "id_rsa.pub" from "C:\Users\[USERNAME]\.ssh" to the "/home/jovyan/.ssh" directory on Matlantis as "/home/jovyan/.ssh/authorized_keys". After saving, a restart of Matlantis is required.

Example: You can execute the following command in the Matlantis terminal to save the id_rsa.pub placed in /home/jovyan as authorized_keys in /home/jovyan/.ssh/.

cat /home/jovyan/id_rsa.pub >> /home/jovyan/.ssh/authorized_keys

After this, you may delete the id_rsa.pub remaining in /home/jovyan.

rm /home/jovyan/id_rsa.pub

3. Preparing the BAT File

Create a BAT file, which is a script to run commands on Windows.

"If you click the URL below, you can obtain `ssh_matlantis.bat`. For example, create a folder such as `C:\Users\[USERNAME]\MyScripts` and save it there (the file name and location are arbitrary)."

https://redirect.matlantis.com/api/me/ssh?script_type=bat

* Note: Depending on your browser or other environment, you may receive warning messages during the download, such as "Is this file dangerous?" or "Can it be trusted?" In such cases, you may not be able to download the file as is. Please disable the security check to proceed with the download. (If you cannot download the file, please refer to the instructions below to create the file manually.)

`ssh_matlantis.bat` contains the following content:

Checking for the existence of the `websocat` executable file.
- If it does not exist, `websocat` (https://github.com/vi/websocat) will be automatically downloaded into the folder containing the `ssh_matlantis.bat` file.
<tenat name>, <matlantis_user_id>, and <notebook_pre_shared_key> are user specific information. (If you obtained the file by clicking the URL above, it has been customized with your information.)

@echo off
setlocal enabledelayedexpansion

:: ============================================================
:: [Configuration] The following 3 values are user-specific.
:: ============================================================
set MATLANTIS_USER_ID=<matlantis_user_id>
set NOTEBOOK_PRE_SHARED_KEY=<notebook_pre_shared_key>
set MATLANTIS_DOMAIN=<tenant_name>.matlantis.com
:: ============================================================
cd /d %~dp0

set BIN_NAME=websocat.x86_64-pc-windows-gnu.exe
set BIN_URL=https://github.com/vi/websocat/releases/download/v1.14.1/%BIN_NAME%
set EXPECTED_HASH=284339b5b86f2b11496137d97b6705bb2ef27e64f21527c1ba240bdb6177ba3b
set WEBSOCAT_PATH=C:\Program Files\Websocat\%BIN_NAME%
set NEED_DOWNLOAD=0

if exist "%BIN_NAME%" (
    set ACTUAL_HASH=
    for /f "skip=1 tokens=1" %%H in ('certutil -hashfile %BIN_NAME% SHA256') do (
        if not defined ACTUAL_HASH set ACTUAL_HASH=%%H
    )
    if "!ACTUAL_HASH!"=="%EXPECTED_HASH%" (
        set WEBSOCAT="%BIN_NAME%"
    ) else (
        echo Version mismatch: the existing file will be replaced with the correct version.
        del %BIN_NAME%
        set NEED_DOWNLOAD=1
    )
) else (
    where %BIN_NAME% >nul 2>&1
    if !errorlevel! equ 0 (
        set WEBSOCAT="%BIN_NAME%"
    ) else if exist "%WEBSOCAT_PATH%" (
        set ACTUAL_HASH=
        for /f "skip=1 tokens=1" %%H in ('certutil -hashfile "%WEBSOCAT_PATH%" SHA256') do (
            if not defined ACTUAL_HASH set ACTUAL_HASH=%%H
        )
        if "!ACTUAL_HASH!"=="%EXPECTED_HASH%" (
            set WEBSOCAT="%WEBSOCAT_PATH%"
        ) else (
            echo Version mismatch: the existing file will be replaced with the correct version.
            set NEED_DOWNLOAD=1
        )
    ) else (
        set NEED_DOWNLOAD=1
    )
)

if "!NEED_DOWNLOAD!"=="1" (
    curl -s -L -o %BIN_NAME% %BIN_URL%
    set ACTUAL_HASH=
    for /f "skip=1 tokens=1" %%H in ('certutil -hashfile %BIN_NAME% SHA256') do (
        if not defined ACTUAL_HASH set ACTUAL_HASH=%%H
    )
    if not "!ACTUAL_HASH!"=="%EXPECTED_HASH%" (
        echo Hash mismatch: the downloaded file may be corrupted. Please try again.
        del %BIN_NAME%
        pause
        exit /b 1
    )
    set WEBSOCAT="%BIN_NAME%"
)

%WEBSOCAT% --binary -H="cookie: matlantis-notebook-pre-shared-key=%NOTEBOOK_PRE_SHARED_KEY%" wss://%MATLANTIS_DOMAIN%/nb/%MATLANTIS_USER_ID%/default/api/ssh-over-ws

4. Create and Saving .ssh/config

Add the following content to the config file(no extention) in "C:\Users\[USERNAME]\.ssh"(create it if it does not exist). Be sure to specify all paths as absolute path.

# SSH configuration for connecting directly to Matlantis
Host matlantis
    ProxyCommand C:\Users\[USERNAME]\MyScripts\ssh_matlantis.bat
    User jovyan
    IdentityFile C:\Users\[USERNAME]\.ssh\id_rsa

# Note: For Windows, use an absolute path like C:\Users\[USER NAME]\.ssh\id_rsa

5. Log in to Matlantis

If you are logged off, please log in to Matlantis.

6. Verifying SSH Connection to Matlantis

You can connect using "ssh matlantis". If it doesn't work, please refer to the troubleshooting guide.

Enter the PowerShell:

ssh matlantis

(actual screen)

Return to Top⏎

Trobleshooting

If you fail to connect to Matlantis via SSH, please check the following items:

Ensure that the BAT file created in step 3 is executable.
Verify the settings in the config file created in step 4:
- Check for any incorrect file paths.
- Ensure that you have the necessary execution permissions.
Restart Matlantis (a restart may be required after uploading the public key in step 2) ; otherwise, you may receive a "Permission denied (publickey)" error.
If Matlantis is not running, you will see a "302 ERROR." Please start Matlantis and try again.
If the websocat executable is not in the folder containing the ssh_matlantis.bat file, it is likely that the automatic download has failed for some reason. Please manually download it using this way.

Return to Top⏎

Downloading websocat manually

Downloading the Installer
User the pre-built executables available in the middle of the Websocat pages.
For the 64bit Windows, download "websocat.x86_64-pc-windows-gnu.exe".
- The appropriate executable file name may differ depending on your system.
- During the download, you might encounter security warnings such as "Is this file dangerous?" If so, you will need to temporarily disable security checks to proceed with the download.
Storing the Executable File
Create a folder named "C:\Program Files\Websocat" and place the downloaded executable file (.exe) from step 1 into it. (The file location can be arbitrary as long as you can execute the command. You will need to set the Path environment variable in Windows to run the command.)
Checking Operation
Verify wih PowerShell. Move to the directory where you stored the executable file, and if you can run websocat as shown below, the preparation is complete.
- Check the version: The version should be returned.
  
  Enter the PowerShell:
```
cd C:\Program Files\Websocat
```
```
.\websocat.x86_64-pc-windows-gnu.exe --version
```
  (actual screen)
- Connection Test: Connect to the Websocat test server (which offers an echo service). For example, type "Matlantis" and if it returns "Matlantis", the setup was successful.
  
  Enter the PowerShell:
```
.\websocat.x86_64-pc-windows-gnu.exe wss://echo.websocket.events
```
  (actual screen)

Return to Top⏎

For Mac (Linux)

The instructions are for Mac, but the setup can also be applied to Linux in the same way.

Install websocat.
```
brew install websocat
```
Generate a private key and public key using "ssh-keygen".

Example: Using rsa(default) with 4096 bits (no passphrase is recommended if using VSCode)
```
ssh-keygen -t rsa -b 4096
```
Upload the public key. The public key is located at "~/.ssh/id_rsa.pub" on your device. Upload it to Matlantis as "/home/jovyan/.ssh/authorized_keys".

Save the "/home/[USERNAME]/ssh_matlantis.sh" file with the following content.

By accessing the URL below, you can download the ssh_matlantis.sh file:

https://redirect.matlantis.com/api/me/ssh

[USERNAME] is your Mac username

We will provide <matlantis_user_id>, <notebook_pre_shared_key>,and <tenat name> upon comletion of the SSH access setup.

#! /bin/bash
set -e

# ============================================================
# [Configuration] The following 3 values are user-specific.
# ============================================================
MATLANTIS_USER_ID=<matlantis_user_id>
NOTEBOOK_PRE_SHARED_KEY=<notebook_pre_shared_key>
MATLANTIS_DOMAIN=<tenant_name>.matlantis.com
# ============================================================

cd $(dirname $0)

websocat_sha256() {
    case "$1" in
        websocat.aarch64-apple-darwin)       echo "c7402a1de17aa5446f86a7fe439cf502c49436c1f2df298c16fd8c2bf092a84e" ;;
        websocat.x86_64-apple-darwin)        echo "45521ba59a6604785543406bf8e398ce7d565d54c09657176afba795dd28f191" ;;
        websocat.x86_64-unknown-linux-musl)  echo "66f8dd3a0394761556339117f8bb5123bddefd44e087af2a72ec22b0bd08d514" ;;
    esac
}

compute_sha256() {
    if command -v sha256sum &> /dev/null; then
        sha256sum "$1" | awk '{print $1}'
    else
        shasum -a 256 "$1" | awk '{print $1}'
    fi
}

OS=$(uname -s)
ARCH=$(uname -m)
FILENAME=""
if [ "$OS" = "Linux" ] && ([ "$ARCH" = "x86_64" ] || [ "$ARCH" = "amd64" ]); then
    FILENAME=websocat.x86_64-unknown-linux-musl
elif [ "$OS" = "Darwin" ]; then
    if [ "$ARCH" = "x86_64" ] || [ "$ARCH" = "amd64" ]; then
        FILENAME=websocat.x86_64-apple-darwin
    elif [ "$ARCH" = "arm64" ] || [ "$ARCH" = "aarch64" ]; then
        FILENAME=websocat.aarch64-apple-darwin
    fi
fi

if [ -f "./websocat" ] && [ -n "$FILENAME" ]; then
    if [ "$(compute_sha256 websocat)" != "$(websocat_sha256 "$FILENAME")" ]; then
        echo "Version mismatch: the existing file will be replaced with the correct version."
        rm websocat
    fi
fi

if ! command -v websocat &> /dev/null && [ ! -f "./websocat" ]; then
    if [ -z "$FILENAME" ]; then
        echo "Unsupported OS or architecture: OS=$OS ARCH=$ARCH"
        exit 1
    fi
    echo "websocat not found, downloading..."
    curl -s -L -o websocat "https://github.com/vi/websocat/releases/download/v1.14.1/$FILENAME"
    if [ "$(compute_sha256 websocat)" != "$(websocat_sha256 "$FILENAME")" ]; then
        echo "Hash mismatch: the downloaded file may be corrupted. Please try again."
        rm websocat
        exit 1
    fi
    chmod +x websocat
fi

if [ -f "./websocat" ]; then
    WEBSOCAT=./websocat
else
    WEBSOCAT=websocat
fi

$WEBSOCAT --binary -H="cookie: matlantis-notebook-pre-shared-key=${NOTEBOOK_PRE_SHARED_KEY}" wss://${MATLANTIS_DOMAIN}/nb/${MATLANTIS_USER_ID}/default/api/ssh-over-ws

Make the file created in step 4 executable using "chmod +x".
```
chmod +x ssh_matlantis.sh
```

Create "~/.ssh/config".

[USERNAME] refer to your Mac username.
Please ensure that the paths /Users/[USERNAME]/ssh_matlantis.sh and ~/.ssh/id_rsa match the actual file paths where you saved them.

# Client to Matlantis direct connection
Host matlantis
ProxyCommand /Users/[USERNAME]/ssh_matlantis.sh
User jovyan
IdentityFile ~/.ssh/id_rsa

# using`server` as a jump host to execute bash commands
Host matlantis
ProxyCommand ssh server -T /Users/[USERNAME]/ssh_matlantis.sh
User jovyan
IdentityFile ~/.ssh/id_rsa

You can connect to Matlantis using "ssh matlantis"
```
ssh matlantis
```
- "302 ERROR" indicates that Matlantis is not running. Please start Matlantis and try again.
- You can also copy files using "scp".

Return to Top⏎

Configuring VSCode (Optional)

Search for "SSH" in Extensions and install "Remote-SSH".

https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh
Connect to SSH > matlantis from the Remote Explorer.
Additionally, please install any other necessary extensions, such as Jupyter Kernels, Python Environments, etc.

Return to Top⏎

Configuring WinSCP (Optional, Windows only)

Here is how to configure WinSCP

Set the following in New Site
- Host name: Matlantiss
- User name: jovyan
- Next, open the Advanced Site Settings from "Advanced...".
  
  　
Advanced Site Settings >Proxy configure as follows.
- Proxy type: local
- Proxy settings:
  For Local proxy command, specify "ssh_matlantis.bat" using "Browse" button.
```
C:\Users\[USERNAME]\MyScripts\ssh_matlantis.bat
```
Advanced Site Settings > Authentication
- Specify the private key file as the "id_rsa" file using the "..." button.
- Convert to Putty format by clicking "OK"
- The screen showing the ppk file setup looks as follows. Close the Advanced Site Settings screen by clicking the OK button.
Name the session and Save it
Select the saved session and connect by clicking "Login".

Return to Top⏎

How to configure the SSH Connection setting in Dashboard > Users

This operation can only be performed by an admin user.

In Dashboard > Users, select a specific user. On the User Information screen, enable "SSH Connection" and click "Update" to save the changes.

Please note that to enable or disable the SSH Connection setting, the user's Matlantis must be stopped. The new setting will be applied the next time Matlantis is started.

Return to Top⏎

Related to

Table of Contents

Change log

Setting Up Matlantis

Setting Up the Client

For Windows

1. Verifying SSH Functionality and Generationg Private and Public Key

2. Uploading Public Key

3. Preparing the BAT File

4. Create and Saving .ssh/config

5. Log in to Matlantis

6. Verifying SSH Connection to Matlantis

Trobleshooting

Downloading websocat manually

For Mac (Linux)

Configuring VSCode (Optional)

Configuring WinSCP (Optional, Windows only)

How to configure the SSH Connection setting in Dashboard > Users

Related articles