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.
Table of Contents
- Setting Up Matlantis
- Setting Up the Client
- Configuring VSCode (Optional)
- Configuring WinSCP (Optional, Windows only)
- How to Configure the SSH Connection setting (Dashboard > Users, admin only)
Change log
- 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
Setting Up the Client
The process differs between Windows and Mac/Linux. Please follow the instructions based on your operating system.
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:
- Please check the parts highlighted in yellow as they depend on the environment.
-
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
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/latest/download/%BIN_NAME%
set WEBSOCAT_PATH=C:\Program Files\Websocat\%BIN_NAME%
where %BIN_NAME% >nul 2>&1
if %errorlevel% equ 0 (
set WEBSOCAT=%BIN_NAME%
) else (
if exist "%WEBSOCAT_PATH%" (
set WEBSOCAT="%WEBSOCAT_PATH%"
) else (
curl -s -L -o %BIN_NAME% %BIN_URL%
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)
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)
- 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 method
- 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.
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)
- Check the version: The version should be returned.
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
MATLANTIS_USER_ID=<matlantis_user_id>
NOTEBOOK_PRE_SHARED_KEY=<notebook_pre_shared_key>
MATLANTIS_DOMAIN=<tenant_name>.matlantis.com
cd $(dirname $0)
if ! command -v websocat &> /dev/null; then
# error if no websocat in the same directory
if [ ! -f ./websocat ]; then
echo "websocat not found, please download and save it to $PATH or in the same directory as this script"
exit 1
fi
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.
# 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
-
[USERNAME] refer to your Mac username.
- 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".
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.
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.
- Specify the private key file as the "id_rsa" file using the "..." button.
- Name the session and Save it
-
Select the saved session and connect by clicking "Login".
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.