Skip to content

Connecting to the Cluster

Your HPC cluster is a remote machine. That means it doesn't have a monitor, keyboard, or mouse plugged into it the way your laptop does. To use it, you open a connection from your local machine over the network and interact with the cluster through a terminal. The tool that makes this possible is called SSH (Secure Shell).

This page will walk you through:

  1. Getting an SSH client ready on your machine
  2. Connecting to the cluster for the first time
  3. What you're looking at once you're in

What is SSH?

SSH (Secure Shell) is a protocol for securely connecting to a remote computer over a network. When you "SSH into" a cluster, you're opening an encrypted channel between your machine and one of the cluster's login nodes. Once connected, you get a terminal session on that remote machine. You can type commands just as if you were sitting in front of it.

The basic SSH command looks like this:

ssh username@hostname
  • username is your account name on the cluster.
  • hostname is the network name or address of the machine you're connecting to.

Your First Mental Model

Think of SSH as making a phone call with caller ID. You need a phone (your SSH client), you need to know the number (the hostname), and the person on the other end needs to recognize you (by your username and credentials) to decide whether to accept the connection. The connection is encrypted, so nobody listening on the wire can eavesdrop.

Step 1: Open a Terminal with an SSH Client

SSH is a command-line tool, so you'll need a terminal application to use it. What you need depends on your operating system.

Good news: You already have everything you need. macOS ships with a built-in terminal that includes an SSH client.

To open it: Applications → Utilities → Terminal

You can also search for "Terminal" in Spotlight (Cmd+Space).

Like macOS, Linux distributions come with SSH built in. Open your distribution's terminal emulator (often called Terminal, Konsole, or GNOME Terminal) and you're ready to go.

Modern Windows (10 and later) includes an SSH client you can use from PowerShell or Command Prompt. Open either one and try typing ssh. If you see usage information, you're all set.

If you prefer a dedicated application, two popular free options are:

  • MobaXterm: Recommended. Bundles a terminal, file transfer client, and X11 server in one package.
  • PuTTY: A lightweight, long-established SSH client.

Note

Most graphical work on Unity should go through Open OnDemand in your browser, no SSH client setup needed. If you do plan to use X11 forwarding, MobaXterm bundles an X11 server and is the easier choice.

Step 2: Connect to the Cluster

Before you can connect, make sure you meet two requirements:

  1. You have a cluster account. If you haven't yet, see Request an Account to learn how to get one.
  2. You're on the right network. As a security measure, most HPC centers don't expose their clusters to the open internet. Make sure you are on Dartmouth's network or connected through a VPN before you try to SSH in.

Personalize this page. Enter your NetID and we'll fill it into every copy-pasteable command below. It's saved only in your browser.

Unity offers two ways to connect:

Method Address Best For
SSH (command line) login.unityhpc.org Terminal access, scripts, file transfers
Open OnDemand (web portal) https://ood.unity.rc.umass.edu/ Jupyter, RStudio, VS Code, file browser

To connect via SSH, use your Dartmouth NetID in the format netid_dartmouth_edu:

ssh your_netid_dartmouth_edu@login.unityhpc.org

SSH key required

Unity uses SSH key authentication. If you haven't set up your key yet, see the account setup instructions.

Open OnDemand uses separate SSO

The Open OnDemand web portal at https://ood.unity.rc.umass.edu/ requires a separate SSO login through your institutional identity provider.

The First Connection: Host Key Verification

The very first time you connect to a new remote machine, your SSH client won't recognize it. It will stop and show you a message similar to this:

The authenticity of host 'login.unityhpc.org (x.x.x.x)' can't be established.
ED25519 key fingerprint is SHA256:abc123xyz...
Are you sure you want to continue connecting (yes/no/[fingerprint])?

This is SSH protecting you from "man-in-the-middle" attacks. The remote server presents a unique "fingerprint." Type yes and press Enter. Your client will save this fingerprint and won't ask you again unless the server's identity changes (which occasionally happens during major system upgrades).

Authenticating

Once the connection is established, you'll be authenticated using your SSH key. If your key is properly configured (see account setup), you'll be logged in automatically. If you set a passphrase on your key, you may be prompted to enter it.

SSH key not working?

If you're asked for a password instead of being authenticated by key, make sure you've added your private key with ssh-add and that the corresponding public key is uploaded in the Unity portal. See the account setup instructions for details.

Step 3: Verify You're Connected

If everything worked, your terminal prompt will change. Instead of showing your local machine's name, it will show the name of the cluster node you've connected to. Something like:

[your_username@login-node ~]$

Congratulations! You're on the cluster. The commands you type now are running on the remote machine, not your laptop.

What's a Login Node?

On a cluster like Unity, the machine you land on when you SSH in is called a login node. It's a shared gateway: a place to manage files, write scripts, and submit jobs. It is not where you run heavy computations! Those happen on separate compute nodes managed by the job scheduler. We'll cover job submission in a later section.

Running graphical applications

Most of your work on Unity will be through the command line, but you'll occasionally need a real graphical interface: a plotting tool, an IDE, MATLAB's desktop, a visualization app.

For that, use Open OnDemand, Unity's web portal. It runs your graphical application as a batch job on a compute node and streams the desktop to your browser over VNC. No SSH client, no X11 server, no setup on your laptop. See the Open OnDemand recipes for a walkthrough.

What you can launch from Open OnDemand

JupyterLab, RStudio, VS Code, MATLAB, Mathematica, and a full Linux Virtual Desktop. If your tool isn't on that list, the Virtual Desktop will run almost anything you'd otherwise reach for X11 to use.

When you really need X11

The old way to run a remote GUI is X11 forwarding: SSH carries the graphical output back to a local X server on your laptop. It still works, but it's the wrong tool for most jobs on a modern cluster (see the warning below).

If you do need it, two rules:

  1. Don't run GUIs on the login node. The login node is a shared gateway. Heavy processes there get killed and they slow the node down for everyone.

  2. Launch the GUI from a compute node by combining ssh -Y with an interactive Slurm allocation:

    ssh -Y your_netid_dartmouth_edu@login.unityhpc.org
salloc -c 2 -p cpu --x11 xclock

    The --x11 flag tells Slurm to forward X back through your SSH session. You cannot do this with sbatch, only salloc.

For this to work, your local machine also needs an X11 server, which is the software that draws the remote windows on your screen.

macOS does not ship with an X11 server. Install XQuartz (free), then log out and back in (or reboot) for it to take effect. After that, ssh -Y will work from your regular Terminal.

Most Linux desktops already include an X11 server. ssh -Y should work out of the box.

  • MobaXterm includes a built-in X11 server. Just connect as usual and graphical applications will forward automatically.
  • PuTTY users will need to install a separate X11 server such as VcXsrv or Xming, and enable X11 forwarding in PuTTY's configuration.

Why Open OnDemand exists

X11 forwarding sends every screen update over the network, one round-trip at a time. A small xclock or a quick plot window is fine. A full IDE, MATLAB's desktop, RStudio, or any visualization tool feels painfully sluggish and often unusable. That isn't a network problem, it's the X11 protocol itself, which is why Unity's recommendation is OnDemand for any non-trivial GUI.

Troubleshooting

Use verbose mode to diagnose problems

Add -v to your SSH command for detailed diagnostic output: 

ssh -v username@hostname
This shows every step of the connection handshake and is the first thing support staff will ask for when helping you debug.

"Connection refused" or "Connection timed out"
You're probably not on the right network. Make sure you're on Dartmouth's network or connected to the VPN, then try again.
"Permission denied"
Double-check your username and password. Remember that both are case-sensitive.
"Host key verification failed"
This usually means the cluster's SSH key has changed (for example, after maintenance). Follow Dartmouth's instructions for updating your known hosts file, or contact Research Computing and Data.
Password prompt doesn't appear / connection hangs
This is often a network or firewall issue. Verify your VPN connection is active and try again.

Summary

Concept What It Means
SSH Encrypted protocol for remote terminal access
SSH client The program on your machine that initiates the connection
Login node The shared machine you land on after connecting
Open OnDemand Web portal that runs graphical apps on compute nodes, streamed to your browser

Next Steps

Practice SSH Connections

Ready to try it out? This interactive widget simulates a local terminal on your machine. You can practice logging in and dealing with common errors before you try the real thing.

Next Steps

Now that you can connect to the cluster, it's time to put it to work. Head to Submit Your First Job to continue.