social-data-attribution-w2/docs/PACE_ICE_VSCODE_SETUP.md

# Connecting VS Code to PACE ICE via Tunnels

> **Author:** Rayan Castilla-Zouine  
> **Team:** eilab-gt / data-attribution  
> **Last Updated:** February 2026

## Why This Matters

Instead of hand-editing code on OnDemand's browser-based VS Code, you can run **your own local VS Code** with AI agents (Codex, Copilot, etc.) and have every file edit and terminal command execute **directly on PACE**. This dramatically speeds up the workflow for the data-attribution pipeline.

---

## How It Works

```
┌──────────────────────┐          Secure Tunnel          ┌──────────────────────────┐
│   Your Laptop        │  ◄──────────────────────────►   │   PACE Compute Node      │
│   (VS Code Desktop)  │                                 │   (GPU, CPU, Storage)    │
│                      │                                 │                          │
│  • You see the files │                                 │  • Files live HERE       │
│  • You type code     │                                 │  • Commands run HERE     │
│  • Codex/Copilot     │                                 │  • sbatch jobs run HERE  │
│    runs HERE but     │                                 │                          │
│    acts THERE ──────►│                                 │  ~/data-attribution/     │
└──────────────────────┘                                 └──────────────────────────┘
```

**Key points:**
- Files **only exist on PACE** (in your scratch/home directory). Nothing is stored locally on your laptop.
- When you edit a file in VS Code, it edits the file **on the cluster** in real-time.
- Your local machine is just a window into the remote filesystem.
- `git add`, `git commit`, `git push` all run **on PACE** and push to GitHub from there.

---

## Prerequisites

| Requirement | Details |
|-------------|---------|
| **GT VPN** | Download GlobalProtect from [vpn.gatech.edu](https://vpn.gatech.edu) |
| **VS Code Desktop** | Download from [code.visualstudio.com](https://code.visualstudio.com) |
| **PACE Account** | Your class must be registered with PACE |
| **GitHub Account** | For tunnel authentication |

---

## One-Time Setup (on PACE)

### 1. Connect to VPN
Open GlobalProtect → `vpn.gatech.edu` → authenticate with GT credentials + 2FA.

### 2. SSH into PACE
```bash
ssh YOUR_GT_USERNAME@login-ice.pace.gatech.edu
```

### 3. Install the VS Code CLI (one-time)
```bash
curl -Lk 'https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-x64' -o ~/vscode_cli.tar.gz
tar -xzf ~/vscode_cli.tar.gz -C ~/
```

### 4. Get a Compute Node and Start the Tunnel
```bash
# Request an interactive node (adjust resources as needed)
salloc --gres=gpu:1 --cpus-per-task=4 --mem=32G --time=04:00:00

# Start the tunnel
~/code tunnel --accept-server-license-terms
```

**First time only:** You'll be given a URL + code to authorize via GitHub. Follow the prompts.  
Give your tunnel a name (e.g., `pace-ice`).

Leave this terminal open.

---

## Connecting from Your Laptop

### 1. Install the Extension
In VS Code Desktop: Extensions → search **"Remote - Tunnels"** (by Microsoft) → Install.

### 2. Connect
`Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows) → **Remote Tunnels: Connect to Tunnel…**  
Sign in with the **same GitHub account** → select your tunnel.

### 3. Open Your Project
Click **Open Folder** → `~/data-attribution`

You're in! The terminal is now a shell on the PACE compute node.

---

## Daily Workflow

Every time you want to work:

```
1. Connect VPN
2. ssh YOUR_GT_USERNAME@login-ice.pace.gatech.edu
3. salloc --gres=gpu:1 --cpus-per-task=4 --mem=32G --time=04:00:00
4. ~/code tunnel
5. In VS Code: Cmd+Shift+P → Remote Tunnels: Connect to Tunnel
```

---

## Using Git

Since files live on PACE, git commands run **in the VS Code terminal** (which is on the cluster):

```bash
git add .
git commit -m "your message"
git push origin main
```

This pushes directly from PACE to GitHub. Your laptop never holds a copy of the code.

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Can't SSH in | Check VPN is connected |
| `code` not found | Re-run the install step (curl + tar) |
| Connection drops | Your `salloc` timed out — request a new node and restart `~/code tunnel` |
| Extensions missing on remote | VS Code will prompt you to install them — click "Install in Tunnel" |

---

## Fixing AI Agent Authentication (Codex, Copilot, etc.)

When connected via a tunnel, AI agent extensions (like Codex) run on the **remote node**. Their OAuth sign-in flow opens your **local browser**, but the callback redirects to `localhost:<port>` — which points to your laptop, not the remote node. This causes `ERR_CONNECTION_REFUSED`.

### Fix 1: Forward the Auth Port (Recommended)

1. In VS Code, click the **PORTS** tab (bottom panel, next to TERMINAL).
2. Click **Forward a Port** (or the `+` button).
3. Enter the port number from the error URL (e.g., `1455`).
4. Retry the sign-in. The browser callback now routes through the tunnel.

### Fix 2: Use an API Key (No Browser Needed)

1. In the Codex panel, click **"Use API Key"**.
2. Get your key from [platform.openai.com/api-keys](https://platform.openai.com/api-keys).
3. Paste it. Done.

### Fix 3: Run Codex CLI in the Terminal

```bash
npm install -g @openai/codex
codex
```

This runs entirely in the terminal on the remote node — no browser redirect needed.

---

## FAQ

**Q: Does editing a file change it on my laptop too?**  
A: **No.** Files only exist on PACE. Your laptop is just a viewer/editor.

**Q: What about my scratch folder on PACE?**  
A: If your project is in `~/scratch/data-attribution`, that's exactly what you're editing. Same files, same location.

**Q: Can I use Codex / Copilot / other AI agents?**  
A: Yes! Install them in VS Code. They send edits through the tunnel and the changes happen on PACE.

**Q: Do I still need OnDemand?**  
A: Not for coding. You might still use OnDemand for other PACE web tools, but your IDE workflow is now fully local.