← Back to Documentation

SSH and Key Authentication

This guide explains what SSH is and how to set it up so you can access your team VMs. If you already have a SSH key pair you don’t need to read this document; instead go to this page to upload your public key.

What is SSH?

SSH stands for Secure SHell and is a way to securely connect to and control remote computers over the internet. You connect with your local computer (e.g. your laptop) to a remote machine (e.g. a Virtual Machine in the cloud) to access a shell session. The connection happens over a secure tunnel and encrypts all traffic between the two machines.

SSH is very common in the industry by all kinds of engineers and developers. If you have ever used Git you have probably indirectly used SSH before, since Git usually talks to remote servers (like Github) via SSH.

During this hackathon you’ll use SSH to connect to the Virtual Machines we have provisioned in our cloud for you. You will use this to deploy your bot code to the server, and you might want to use it to debug your code on the Virtual Machine.

SSH Key Authentication

SSH authentication is based off cryptographic key pairs. To use SSH you need to generate your own key pair that the server will trust.

An SSH key pair is, like the name suggests, a set of two keys: a private key and a public key. The private key is a secret that you should never share with someone else. The public key is not secret: this is the part of the key that other parties use to verify that the SSH connection actually came from you (or rather, from the private key in the key pair).

Both keys are typically stored in your computer in the directory ~/.ssh. You should check there first before you generate any new key pairs, so you don’t overwrite any existing ones!

# A typical ~/.ssh folder. In here we have a key pair:
# - id_ed25519, the private key
# - id_ed25519.pub, the public key
$ ls ~/.ssh
authorized_keys  config  id_ed25519  id_ed25519.pub  known_hosts

Generating Your SSH Key Pair

Open a terminal (PowerShell or WSL if you are on Windows) and run the following command, but with your email:

ssh-keygen -t ed25519 -C "your-email@example.com"

This will prompt you for some options:

  1. Press Enter to accept the default location (~/.ssh/id_ed25519)
  2. Enter a passphrase: optional but recommended. This is a password that is required to access the private key, so remember it!
  3. Confirm the passphrase

If you get an error that Ed25519 isn’t supported, run this instead:

ssh-keygen -t rsa -b 4096 -C "your-email@example.com"

Adding your key to the ssh-agent

If you set a passphrase on your key when generating it you can start an ssh-agent on your laptop. The ssh-agent remembers the passphrase and reuses it for a set amount of time so you don’t need to retype it too often.

To start the ssh-agent run:

  • On macOS/Linux/WSL:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
  • On Windows (PowerShell):
Get-Service ssh-agent | Set-Service -StartupType Manual
Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519

Upload your public key

Your public key is stored in a file ending in .pub inside the directory ~/.ssh. You need to copy this and upload it here so we can give you access to your team VM.

The public key should look something like this:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDIhz2GK/XCUj4i6Q5yQJNL1MXMY0RxzPV2QrBqfHrD your-email@example.com

⚠️ Important: Never share your private key (the file without .pub). Only share the public key!

Connecting to a Server

To connect to a server with SSH you just run the ssh command and give it the machine you want to connect to. If you set a passphrase on your key pair you’ll be prompted to enter it. For example:

ssh username@example.com

In this hackathon we will need to have a bit more configuration to reach your machines. We have put this into a configuration file for you: simply download that file, save it somewhere close to the project you will be working on, and give it to the ssh command via the -F flag:

ssh -F ssh.config <team-host>