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:
- Getting an SSH client ready on your machine
- Connecting to the cluster for the first time
- 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:
usernameis your account name on the cluster.hostnameis 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
If you plan to run graphical applications on the cluster (see X11 Forwarding below), MobaXterm is the easier choice because it handles the X11 setup for you.
Step 2: Connect to the Cluster¶
Before you can connect, make sure you meet two requirements:
- You have a cluster account. If you haven't yet, see Request an Account to learn how to get one.
- 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.
Each of Dartmouth's HPC systems has its own address:
| Host | Description | Address |
|---|---|---|
| Discovery | Dartmouth's primary HPC cluster with a shared job scheduler | discovery.dartmouth.edu |
| Andes | Large shared-memory system for memory-intensive workloads | andes.dartmouth.edu |
| Polaris | Large shared-memory system for memory-intensive workloads | polaris.dartmouth.edu |
| Babylon | Thayer / CS shared-memory nodes (12 hosts) | babylon1.dartmouth.edu – babylon12.dartmouth.edu |
To connect, use your NetID (which is also your HPC account name) and the address (a.k.a. hostname) of the system you want to log in to.
For example, to log into the Discovery cluster:
To connect to one of Dartmouth's shared-memory systems:
If you are a member of Thayer or in the CS program, you can log into one of the Babylon systems, for example:
To help you choose, check out the Babylon usage page and pick one with a low user count.
Once you type the ssh command and hit Enter, you'll be prompted for your password. Type it in, but note that the cursor won't move and no characters will appear. This is normal; it's a security feature, not a bug. Press Enter when you've finished typing your password.
Nothing Shows When I Type My Password!
This catches almost everyone the first time. When you type your password at an SSH prompt, the terminal deliberately shows nothing. No dots, no asterisks, no cursor movement. Just type your password and press Enter.
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:
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 Discovery, 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.
On shared-memory systems, there typically is no separate login node. You SSH directly into the machine itself and run your work there. Be mindful of other users who may be sharing the same system.
X11 Forwarding: Graphical Applications¶
Most of your work on the cluster will be through the command line. But occasionally you may need to run an application with a graphical interface: A plotting tool, MATLAB's desktop, or maybe a config tool.
X11 forwarding lets the cluster send graphical output back to your local screen over the SSH connection. You enable it by adding the -Y flag:
For this to work, your local machine needs an X11 server, which is the software that knows how to draw those 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.
Complex GUI applications will be slow
X11 forwarding works by sending every screen update over the network, one round-trip at a time. Simple, lightweight GUIs (an xterm, a small plot window) are usually fine, but complex applications like MATLAB's desktop, Jupyter notebooks in a browser, RStudio, or heavy visualization tools will feel painfully sluggish and often unusable. This is a fundamental limitation of the X11 protocol, not something a faster network alone can fix.
For a better graphical experience, consider:
- Open OnDemand: Dartmouth's web-based portal that provides full desktop sessions and interactive applications (MATLAB, RStudio, Jupyter) directly in your browser, with no X11 setup required.
- Running headless: do the computation on the cluster, save figures to files, and view them on your local machine.
Troubleshooting¶
Use verbose mode to diagnose problems
Add -v to your SSH command for detailed diagnostic output:
- "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.
- 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 |
| X11 forwarding | Sending graphical output from the cluster to your screen |
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.