Revise GitHub access instructions for sandbox

Updated the instructions for creating a Personal Access Token (PAT) for GitHub, emphasizing repo-scoped access and clarifying the importance of not using main SSH keys. Adjusted the section on SSH key generation to focus on PAT usage instead.

Author: FrankRay78

docs/wsl-claude-sandbox.md

@@ -1,6 +1,6 @@
 # Isolated WSL Sandbox for Claude Code
 
-A WSL2 Ubuntu instance configured for running `claude --dangerously-skip-permissions` with meaningful isolation from the Windows host: separate filesystem, no Windows PATH inheritance, read-only access to Windows files, no LAN reachability, sandbox-only SSH credentials.
+A WSL2 Ubuntu instance configured for running `claude --dangerously-skip-permissions` with meaningful isolation from the Windows host: separate filesystem, no Windows PATH inheritance, read-only access to Windows files, no LAN reachability, sandbox-only repo credentials.
 
 This manual covers the happy path only. Adapt commands to your own usernames, paths, and project repos.
 
@@ -21,13 +21,15 @@ Why: keeps the sandbox separate from your main dev environment, so a misbehaving
 1. Download the Ubuntu 24.04 WSL image from <https://releases.ubuntu.com/noble/> — pick the file ending in `.wsl`.
 
 2. From **PowerShell** (any window, not WSL):
-   ```powershell
+
+   ```
    mkdir C:\WSL\Ubuntu-Claude
    wsl --install --from-file C:\path\to\downloaded.wsl --name Ubuntu-Claude
    ```
 
 3. Launch and create your user account when prompted:
-   ```powershell
+
+   ```
    wsl -d Ubuntu-Claude
    ```
 
@@ -39,13 +41,13 @@ Why: turns off Windows PATH inheritance (so the sandbox can't run `notepad.exe`
 
 Inside the sandbox:
 
-```bash
+```
 sudo nano /etc/wsl.conf
 ```
 
 Replace the contents with (substitute your username for `frankray`):
 
-```ini
+```
 [boot]
 systemd=true
 
@@ -71,7 +73,7 @@ Note: `interop.enabled = true` is required for VS Code's WSL extension to instal
 
 Apply by exiting and running from PowerShell:
 
-```powershell
+```
 wsl --shutdown
 ```
 
@@ -85,13 +87,13 @@ Why: `automount.enabled = true` mounts all Windows drives. If you have drives wi
 
 Create a systemd unit (substitute your drive letter for `d`):
 
-```bash
+```
 sudo nano /etc/systemd/system/unmount-mnt-d.service
 ```
 
 Paste:
 
-```ini
+```
 [Unit]
 Description=Unmount /mnt/d to keep it invisible to the sandbox
 After=local-fs.target
@@ -108,7 +110,7 @@ WantedBy=multi-user.target
 
 Enable:
 
-```bash
+```
 sudo systemctl daemon-reload
 sudo systemctl enable unmount-mnt-d.service
 ```
@@ -125,15 +127,15 @@ Why: by default the sandbox can reach your home router, NAS, other machines on y
 
 First, find your WSL gateway IP (changes per-machine):
 
-```bash
+```
 ip route | awk '/default/ {print $3}'
 ```
 
 Substitute the result wherever you see `172.26.80.1` below.
 
 Install and configure UFW:
 
-```bash
+```
 sudo apt update
 sudo apt install -y ufw
 
@@ -163,14 +165,18 @@ Note: if WSL renumbers its virtual network (rare, but happens on some Windows up
 
 Why: minimal stack for .NET development plus Claude Code.
 
-```bash
+```
 sudo apt update
 sudo apt install -y curl git build-essential ca-certificates
 
 # .NET SDK (Ubuntu 24.04 ships .NET in its own repos — no Microsoft repo needed)
 sudo apt install -y dotnet-sdk-8.0
 dotnet --version
 
+# GitHub CLI (needed for PR workflows from the sandbox)
+sudo apt install -y gh
+gh --version
+
 # Claude Code (Anthropic's official installer)
 curl -fsSL https://claude.ai/install.sh | bash
 claude --version
@@ -180,40 +186,89 @@ First run of `claude` will walk you through authentication via browser.
 
 ---
 
-## Step 6: Generate a sandbox-only SSH key and clone
+## Step 6: Create a repo-scoped PAT and clone
+
+Why: don't give the sandbox access to your whole GitHub account. A fine-grained Personal Access Token scoped to a single repo means a compromised sandbox can only damage that one repo — every other repo on your account is invisible to it. This single token handles both git operations (clone, fetch, push over HTTPS) **and** `gh` CLI operations (PR create, comment) — no separate SSH key needed.
+
+### 6a. Generate the PAT on GitHub
+
+In your browser, go to <https://github.com/settings/personal-access-tokens/new> and fill in:
+
+- **Token name:** `Claude Sandbox - <repo name>` (e.g. `Claude Sandbox - NetPace`)
+- **Expiration:** 90 days is reasonable. (Avoid "No expiration" — rotation is good hygiene.)
+- **Repository access:** select **"Only select repositories"** → pick the single repo you want the sandbox to work on.
 
-Why: never copy your main SSH keys into the sandbox. Generate a fresh key here; if it's ever compromised, you revoke only the sandbox's access.
+Under **Repository permissions**, set these (leave everything else as "No access"):
 
-```bash
-ssh-keygen -t ed25519 -C "claude-sandbox" -f ~/.ssh/id_ed25519
-cat ~/.ssh/id_ed25519.pub
+- **Contents:** Read and write — git push/pull
+- **Pull requests:** Read and write — `gh pr create`
+- **Issues:** Read and write — `gh pr comment` (PR comments are issue comments via the API)
+- **Metadata:** Read-only (auto-selected)
+
+Click **Generate token**. Copy the `github_pat_...` value shown — GitHub only displays it once.
+
+### 6b. Configure the sandbox to use the PAT
+
+In the sandbox, store the token as an environment variable that `gh` picks up automatically:
+
+```
+echo 'export GH_TOKEN="github_pat_xxxxx"' >> ~/.bashrc
+source ~/.bashrc
 ```
 
-Copy the output line. On GitHub: **Settings → SSH and GPG keys → New SSH key** → paste → save.
+(Replace `github_pat_xxxxx` with your actual token.)
 
-Test:
+Verify `gh` is using it:
 
-```bash
-ssh -T git@github.com
+```
+gh auth status
 ```
 
-Configure git identity (use your GitHub noreply email to keep your real email private):
+Should report `Logged in to github.com account <you> (GH_TOKEN)` with the token starting `github_pat_`.
 
-```bash
+Configure git to use `gh` as its credential helper for HTTPS:
+
+```
+gh auth setup-git
+```
+
+### 6c. Configure git identity
+
+Use your GitHub noreply email to keep your real email private:
+
+```
 git config --global user.name "yourusername"
 git config --global user.email "<id>+yourusername@users.noreply.github.com"
 ```
 
 Find your noreply address at <https://github.com/settings/emails>.
 
-Clone your project:
+### 6d. Clone the project
 
-```bash
+```
 mkdir -p ~/projects
 cd ~/projects
-git clone git@github.com:youruser/yourrepo.git
+git clone https://github.com/youruser/yourrepo.git
 ```
 
+Note the HTTPS URL — the PAT authenticates over HTTPS, not SSH. No SSH keys are involved.
+
+### 6e. Verify isolation
+
+Confirm the sandbox can't reach any other private repo:
+
+```
+git clone https://github.com/youruser/<some-other-private-repo>.git /tmp/test
+```
+
+Should fail with `403 - Write access to repository not granted` or `Repository not found`. That failure is the proof your isolation is working — clean up with `rm -rf /tmp/test`.
+
+Note: cloning a *public* repo will still succeed (anyone on the internet can clone public repos, with or without auth). The real test of isolation is whether private repos are reachable.
+
+### 6f. Token rotation
+
+The PAT expires on the date you chose. When that day comes, GitHub will email you. To renew: generate a new PAT at the same URL with the same settings, then edit the `GH_TOKEN` line in `~/.bashrc` and `source ~/.bashrc`. Under a minute's work.
+
 ---
 
 ## Step 7: Connect VS Code
@@ -226,7 +281,7 @@ Why: VS Code's WSL extension installs a server inside the sandbox and connects t
 4. `File → Open Folder` → `/home/<username>/projects/<repo>` → Open.
 5. When prompted, install the **C# Dev Kit** (Microsoft) **into WSL: Ubuntu-Claude**, not locally.
 
-The integrated terminal (`Ctrl+\``) runs inside the sandbox. Confirm by checking the prompt shows your sandbox hostname.
+The integrated terminal (`Ctrl+``) runs inside the sandbox. Confirm by checking the prompt shows your sandbox hostname.
 
 ---
 
@@ -236,29 +291,32 @@ Why: rollback insurance. If Claude trashes the instance later, restore from a sn
 
 From PowerShell:
 
-```powershell
+```
 mkdir C:\WSL\backups -ErrorAction SilentlyContinue
 wsl --export Ubuntu-Claude C:\WSL\backups\ubuntu-claude-final.tar
 ```
 
 Recommended snapshots to keep:
+
 - **Baseline** — after Step 4 (isolation done, no tooling yet). Useful for rebuilds with different tooling.
 - **Working** — after Step 5 (tooling installed). Useful if a later config change breaks things.
 - **Final** — after Step 7 (fully configured). Your day-to-day rollback point.
 
 Restore any snapshot with:
 
-```powershell
+```
 wsl --shutdown
 wsl --unregister Ubuntu-Claude
 wsl --import Ubuntu-Claude C:\WSL\Ubuntu-Claude C:\WSL\backups\<snapshot>.tar
 ```
 
+Note: snapshots include `~/.bashrc` with the PAT in it. Treat the tar files as sensitive — anyone who can read them gets the token (scoped to your one repo, but still). Don't sync them to cloud storage, share them, or check them into version control.
+
 ---
 
 ## Step 9: Run Claude
 
-```bash
+```
 cd ~/projects/<repo>
 claude --dangerously-skip-permissions
 ```
@@ -267,7 +325,7 @@ claude --dangerously-skip-permissions
 
 ## Operational notes
 
-**Don't put real credentials in this sandbox.** No AWS/Azure/GCP CLI logins, no production API keys, no SSH keys from your main account. The SSH key created here should be sandbox-only.
+**Don't add other credentials to this sandbox.** No AWS/Azure/GCP CLI logins, no production API keys, no SSH keys, no `gh auth login` (which would replace your scoped PAT with an account-wide OAuth token). The PAT created in step 6 should be the *only* credential.
 
 **Don't `cd` into mounted Windows directories for project work.** Files at `/mnt/c/...` are read-only and slow over 9P. Keep work in `~/projects/`.