# Claude Code — Remote SSH Connection Setup (Windows)

## Claude Code — Remote SSH Connection Setup (Windows)

### Prerequisites

- Claude Code desktop app installed on Windows
- Target machine running Linux/macOS on your LAN
- OpenSSH client installed on Windows (built-in since Windows 10 1809)
- Network access between the two machines

---

#### Step 1 — Verify OpenSSH is installed on Windows

Open **PowerShell as Administrator** and run:

```powershell
Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH.Client*'
```

If the state shows `NotPresent`, install it:

```powershell
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
```

---

#### Step 2 — Fix "Host denied (verification failed)"

This error means SSH cannot verify the remote machine's host key.

##### Option A — Remove stale host key (most common fix)

```powershell
# Replace 192.168.1.x with your remote machine's IP
ssh-keygen -R 172.17.1.x
```

Then test the connection manually to accept the new key:

```powershell
ssh root@172.17.1.x
# Type "yes" when prompted about the host fingerprint
```

##### Option B — Edit known\_hosts manually

Open the file:

```powershell
notepad C:\Users\YourUsername\.ssh\known_hosts
```

Find and delete the line containing your remote machine's IP or hostname, then save.

##### Option C — First-time connection (no prior key)

Just connect once manually and accept the fingerprint:

```powershell
ssh root@172.17.1.x
# Answer "yes" at the prompt
```

---

#### Step 3 — Generate an SSH key pair (skip if you already have one)

```powershell
# Check for an existing key first
dir C:\Users\YourUsername\.ssh\id_ed25519

# If no key exists, generate one
ssh-keygen -t ed25519 -C "your_email@example.com"
# Press Enter to accept the default path
# Set a passphrase or leave it blank
```

---

#### Step 4 — Copy your public key to the remote machine

##### From Windows PowerShell:

```powershell
# Replace user and IP with your values
type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh root@172.17.1.x "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
```

##### If that fails, do it manually:

1. Print your public key: ```powershell
    type C:\Users\YourUsername\.ssh\id_ed25519.pub
    ```
2. Copy the output.
3. SSH into the remote machine with a password: ```powershell
    ssh root@172.17.1.x
    ```
4. On the remote machine: ```bash
    mkdir -p ~/.ssh
    echo "PASTE_YOUR_PUBLIC_KEY_HERE" >> ~/.ssh/authorized_keys
    chmod 600 ~/.ssh/authorized_keys
    chmod 700 ~/.ssh
    ```

##### Test passwordless login:

```powershell
ssh root@172.17.1.x
# Should log in without a password prompt
```

---

#### Step 5 — Install Claude Code on the remote machine

Claude Code must be installed on the remote machine for remote development to work.

```bash
# On the remote Linux machine
npm install -g @anthropic-ai/claude-code
```

Verify:

```bash
claude --version
```

---

#### Step 6 — Add SSH config entry (recommended)

This makes connections easier and is required by Claude Code's remote feature.

Open or create `C:\Users\YourUsername\.ssh\config` in a text editor:

```powershell
notepad C:\Users\YourUsername\.ssh\config

```

Add an entry:

```
Host myserver
    HostName 172.17.1.x
    User your_username
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 60
    ServerAliveCountMax 3
```

Test it:

```powershell
ssh myserver
```

---

#### Step 7 — Connect from Claude Code (Windows app)

##### Method A — Via the GUI

1. Open the **Claude Code** desktop app.
2. Click the **remote connection icon** (or go to **File → Connect to Remote**).
3. Enter the SSH connection string: ```
    ssh://root@172.17.1.x
    ```
    
    Or if you set up a config alias in Step 6: ```
    ssh://myserver
    ```
4. Select the remote working directory you want to open.
5. Click **Connect**.

##### Method B — Via the terminal inside Claude Code

Open the integrated terminal in Claude Code and run:

```bash
# Navigate to a remote project
claude --remote ssh://root@172.17.1.x /path/to/project
```

##### Method C — Launch from PowerShell

```powershell
claude --remote ssh://myserver /home/user/myproject
```

---

### Troubleshooting

<table id="bkmrk-error-cause-fix-host"><thead><tr><th>Error</th><th>Cause</th><th>Fix</th></tr></thead><tbody><tr><td>`Host denied (verification failed)`</td><td>Stale or missing host key</td><td>Run `ssh-keygen -R <ip>` then reconnect</td></tr><tr><td>`Permission denied (publickey)`</td><td>Key not on remote</td><td>Repeat Step 4</td></tr><tr><td>`Connection refused`</td><td>SSH not running on remote</td><td>`sudo systemctl start ssh` on remote</td></tr><tr><td>`Connection timed out`</td><td>Firewall or wrong IP</td><td>Check firewall, verify IP with `ip addr` on remote</td></tr><tr><td>`claude: command not found` on remote</td><td>Claude Code not installed</td><td>Repeat Step 5</td></tr></tbody></table>

---

### Quick Reference

```powershell
# Remove stale host key
ssh-keygen -R 192.168.1.x

# Test SSH connection
ssh user@192.168.1.x

# Test SSH config alias
ssh myserver

# Copy public key to remote
type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh user@192.168.1.x "cat >> ~/.ssh/authorized_keys"

# Connect Claude Code to remote
claude --remote ssh://myserver /home/user/project

```

---

### File Locations

<table id="bkmrk-file-path-ssh-privat"><thead><tr><th>File</th><th>Path</th></tr></thead><tbody><tr><td>SSH private key</td><td>`C:\Users\YourUsername\.ssh\id_ed25519`</td></tr><tr><td>SSH public key</td><td>`C:\Users\YourUsername\.ssh\id_ed25519.pub`</td></tr><tr><td>Known hosts</td><td>`C:\Users\YourUsername\.ssh\known_hosts`</td></tr><tr><td>SSH config</td><td>`C:\Users\YourUsername\.ssh\config`</td></tr></tbody></table>