Skip to main content

​
About SSH

SSH (Secure Shell) is a protocol for safely connecting to remote servers. It encrypts your connection so you can:
  • Log in securely
  • Run commands remotely
  • Transfer files without exposing your data
Vast.ai instances are configured to accept keys only - Password authentication is disabled for improved security.

​
Quick start: Generate and add your SSH key to your Vast account

  • Terminal
  • Vast CLI
1. Generate a SSH key pair in your terminal
ssh-keygen -t ed25519 -C "your_email@example.com"
  1. Creates two files (by default in ~/.ssh/):
    • id_ed25519 → your private key (keep safe, never share).
    • id_ed25519.pub → your public key (safe to share, add to servers).
  2. -C “your_email@example.com” is optional. Whatever you put there is stored as a comment in the public key file (e.g., id_ed25519.pub). It’s just for identification (helpful if you use multiple keys), not for security.
When you run ssh-keygen -t ed25519 in Windows PowerShell, the keys are created in your Windows user profile folder: C:\Users\<YourUsername>\.ssh\
2. Copy your public key.
# Print the public key
cat ~/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZ9DdI1NTE5AAAAIHWGYlMT8CxcILI/i3DsRvX74HNChkm4JSNFu0wmcv0a
3. Add it in your vast account
  • Adding a key to your account keys only applies to new instances.
  • Existing instances will not get the new key automatically. To add a key, use the instance-specific SSH interface.
  • For VM instances, changing keys requires recreating the VM.

​
Connecting to your Instance

Start a new instance and click the SSH icon to see your connection information.
Connection details

Terminal Connection Options

Now you can enter the connection command string into your terminal
Bash
ssh -p 20544 root@142.214.185.187 -L 8080:localhost:8080

The authenticity of host '[142.214.185.187]:20544 ([142.214.185.187]:20544)' can't be established.
ED25519 key fingerprint is SHA256:WTUphznpN0zikMp+L5EtZpiCH6EeZ2PA/7+DSXDRjT0.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
You should now see a screen similar to this. You will, by default, be placed into a tmux session.
Instance SSH session

Connected to Instance

​
Direct vs Proxy Connections

Vast offers both proxy (default) and direct connection methods for SSH:
  • Proxy SSH: Works on all machines, slower for data transfer, uses Vast proxy server
  • Direct SSH: Requires machines with open ports, faster and more reliable, preferred method

​
Tmux

We connect you to a tmux session by default for reliability and to prevent unintentional termination of foreground processes. You can create a new bash terminal window with ctrl+b + c. Cycle through your windows with ctrl+b + n There is an excellent guide for getting to grips with tmux at https://tmuxcheatsheet.com If, however, you would prefer to disable TMUX, you can apply the following either in a terminal or from your template’s on-start section.
Text
touch ~/.no_auto_tmux

​
SSH Local Port Forwarding

An often overlooked feature of SSH is its ability to forward local ports to another machine. When you access a server remotely over SSH, you can make ports from the remote machine available as if they were listening on your own device. This is a secure alternative to opening ports on the public interface as all data is transported over the SSH connection.
Bash
ssh -p 1234 root@180.123.123.123 -L 8080:localhost:8080 -L 5000:localhost:5000
This SSH command connects to the remote instance and sets up local port forwarding (SSH tunneling): Connection details:
  • Connects to IP 180.123.123.123 as user root
  • Uses port 1234 instead of the default SSH port 22
Port forwarding (the key part):
  • -L 8080:localhost:8080 - Creates a tunnel so when you access localhost:8080 on your local machine, it forwards to port 8080 on the remote server
  • -L 5000:localhost:5000 - Same thing for port 5000
You can repeat the -L arguments to forward as many ports as you need. What this means: After connecting, you can open your web browser and go to https://localhost:8080 or http://localhost:5000 on your local computer, and you’ll actually be accessing services running on those ports on the remote server. It’s like creating secure “tunnels” through the SSH connection to reach applications on the remote machine that might not be directly accessible from the internet.

​
SSH Alternative - Jupyter Terminal

As a simple alternative to SSH, you might like to consider Jupyter Terminal instead. All instances started in Jupyter launch mode will have this enabled. It is a very straightforward web-based terminal with session persistence. It’s great for a quick CLI session. Access the terminal from the SSH connections interface.

​
Troubleshooting

​
Permission Denied (publickey)

If you get this error when trying to SSH:
  1. Ensure your SSH key is added to your Vast account
  2. Verify you’re using the correct private key
  3. Check key file permissions: chmod 600 ~/.ssh/id_ed25519
  4. Use -vv flag for detailed debug info: ssh -vv -p PORT root@IP

​
SSH Key Changes

  • New account keys only apply to NEW instances created after adding the key
  • Existing instances keep their original keys (won’t get new keys automatically)
  • For VM instances, changing keys requires recreating the VM
  • To add keys to existing instances, use the instance-specific SSH interface

​
General Connection Issues

You can often determine the exact cause of a connection failure by using the -vv arguments with ssh to get more information. Common reasons include:
  • Using the wrong private key
  • Incorrect permissions for your private key
  • Public key not added to instance or account
  • Connecting to the wrong port

​
SCP & SFTP File Transfer

Both SCP (Secure Copy Protocol) and SFTP (SSH File Transfer Protocol) are tools for securely transferring files that piggyback on the SSH protocol. They use the same authentication and encryption as SSH.

​
SCP (Secure Copy Protocol)

  • What it is: Simple, command-line tool for copying files between local and remote machines
  • Best for: Quick, one-time file transfers
  • Syntax: scp -P <port> source destination
Examples:
Bash
# Copy file TO instance
scp -P <ssh_port> my_file.txt root@<instance_ip>:/workspace/
# Copy file FROM remote server
scp -P <ssh_port> root@<instance_ip>:/workspace/my_file.txt ./
# Copy entire directory
scp -P <ssh_port> -r  myfolder/ root@<instance_ip>:/workspace/

​
SFTP (SSH File Transfer Protocol)

  • What it is: Interactive file transfer program with a full command set
  • Best for: Managing files, browsing directories, multiple operations
  • Usage: CLI or GUI tools available
Example:
Bash
# Establish connection
sftp -P <ssh_port> root@<instance_ip>

Welcome to vast.ai. If authentication fails, try again after a few seconds, and double check your ssh key.
Have fun!
Connected to 79.116.73.220.
sftp> ls
hasbooted   onstart.sh
Note that both scp and sftp take the -P argument in uppercase. This differs from the ssh command which uses lowercase.

​
VS Code Integration

Once you have your ssh keys set up, connecting to VS Code is quite straightforward. We will cover the basics here.

​
Install the Remote SSH extension

You will need to add the remote extension named ‘Remote - SSH’.

​
Open Remote Window

Click the open remote window button.

Open Remote Window

Enter your ssh address details in the box that appears at the top of your window
Now simply allow a moment for VS code to configure the instance and you will be able to work with the instance as if it was a local machine. For more information, see the VS Code documentation.

​
Windows GUI Clients

For Windows users who prefer GUI tools, please see our Windows Connection Guide for detailed setup instructions for PuTTY, MobaXterm, and other GUI clients.