Isambard-AI Setup Guide

This document provides step-by-step instructions to set up and use Isambard-AI.

---

📑 Table of Contents

• 🚀 First Things First
• 💻 Connect via Terminal
  • 1. Install Clifton
  • 2. Generate an SSH Key
  • 3. Authenticate with Clifton
  • 4. Configure & Connect
• 🖥️ Connect VS Code via Remote Tunnel
  • 1. Install VS Code CLI on Login Node
  • 2. Submit a Jobscript
  • 3. Connect via GitHub
• 🛠️ Final Setup Steps

---

🚀 First Things First

1. Ask your supervisor for access to the ISAMBARD-AI Supercluster.
2. Your supervisor will send an invitation to your Manchester student email. Accept the invitation.
3. Go to the Isambard Portal.
4. When prompted to choose an access request type, select:
   University Login (MyAccessID) → login with your Manchester email and password.
5. Once access is granted to a project, you should see something like this:
   

---

💻 Connect via Terminal

The BriCS facilities provide a command-line tool called Clifton.
Clifton is used to obtain SSH certificates and configure your SSH client. Certificates are valid for 12 hours.

1. Install Clifton

Apple Silicon (macOS ARM64):

curl -L https://github.com/isambard-sc/clifton/releases/latest/download/clifton-macos-aarch64 -o clifton
chmod u+x clifton
sudo mv clifton /usr/local/bin/

Linux (including WSL):

curl -L https://github.com/isambard-sc/clifton/releases/latest/download/clifton-linux-musl-x86_64 -o clifton
chmod u+x clifton
mkdir -p ~/.local/bin
mv clifton ~/.local/bin/

---

2. Generate an SSH Key

Follow GitHub’s documentation.

Note: Only modern SSH keys are supported (e.g. RSA ≥ 3072 bits, Ed25519).
Keys must include:

-----BEGIN OPENSSH PRIVATE KEY-----

---

3. Authenticate with Clifton

clifton auth --identity /path/to/ssh_key

• This will redirect you to a browser → login using University Login (MyAccessID).
• After successful authentication, you’ll see something like:

Successfully authenticated as YOUR_EMAIL (SHORT_NAME) and downloaded SSH certificate for projects:
 - PROJECT_NAME

Certificate file written to ~/.ssh/id_ed25519-cert.pub
Certificate valid for 11 hours and 59 minutes.
You may now want to run `clifton ssh-config write` to configure your SSH config aliases.

---

4. Configure & Connect

1. Write the SSH key to your local config:

   clifton ssh-config write

2. Connect to the login node:

   ssh <PROJECT_ID>.aip2.isambard

---

🖥️ Connect VS Code via Remote Tunnel

1. Install VS Code CLI on Login Node

curl --location --output vscode_cli.tar.gz "https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-arm64"
mkdir -p ~/opt/vscode_cli
tar -C ~/opt/vscode_cli --extract --verbose --file vscode_cli.tar.gz

---

2. Submit a Jobscript

Create a file named vscode_code_tunnel.sh:

#!/bin/bash
#SBATCH --job-name=code_tunnel
#SBATCH --gpus=1            # Allocates 72 CPU cores + 115GB memory
#SBATCH --time=1:00:00
#SBATCH --output=code_tunnel_%j.out

module load brics/nano
# Start named VS Code tunnel for remote connection to compute node
~/opt/vscode_cli/code tunnel --name "i-ai_compute"

Run it:

sbatch vscode_code_tunnel.sh

---

3. Connect via GitHub

1. Open GitHub Device Login.
2. For the first run, you’ll be prompted for an 8-digit code, which can be found in the jobscript output file, e.g. code_tunnel_1182526.out.
3. Open VS Code → bottom-left corner → Connect to Tunnel → choose GitHub.

✅ For subsequent connections:
Just resubmit the jobscript and directly connect via “Connect to Tunnel” in VS Code.

Note: If you update VS Code locally, redo Step 1 (Install VS Code CLI on Login Node) to avoid version mismatch errors.

---

🛠️ Final Setup Steps

1. Install Miniforge to enable PyTorch on GPU:
   Guide: Installing Python Environment.

2. Follow this tutorial for setting up a Distributed Training Environment in PyTorch:
   Distributed Training Guide.

3. Familiarize yourself with the SLURM Workload Manager used by Isambard:
   SLURM Documentation.

   (It’s very similar to the CSF SLURM system.)

---

Happy Coding!