# Remote llama.cpp Server Setup for OpenCode

When running OpenCode on a different machine than your llama.cpp servers, you need three things to make it work.

## 1. Network Reachability

The llama-server must bind to `0.0.0.0` (all interfaces), not `127.0.0.1`. Most systemd unit files already use `--host 0.0.0.0`.

**Check:**
```bash
grep -oP -- '--host \K\S+' /etc/systemd/system/llama-server*.service
```

## 2. Firewall (UFW / nftables / iptables)

UFW on the server machine blocks inbound ports by default. Each llama-server port needs an allow rule for the client subnet.

**Open ports for a LAN subnet:**
```bash
for port in 8081 8082 8090 9021 9022 9023 9024 9025; do
  sudo ufw allow from 192.168.1.0/24 to any port $port proto tcp comment "llama-server"
done
```

**Verify:**
```bash
sudo ufw status | grep llama-server
# Output should show each port ALLOW from your subnet
```

## 3. Connection Methods

Use whichever is available:

| Method | Reachability | SSH Control | Notes |
|--------|-------------|-------------|-------|
| **LAN IP** (192.168.x.x) | Needs UFW open | `ssh user@192.168.1.50` | Works if same subnet |
| **Tailscale IP** (100.x.x.x) | Usually works for HTTP | Needs `tailscale up --ssh` | SSH may need explicit Tailscale SSH config |

### Tailscale SSH Setup (if preferred over LAN)

On the server machine:
```bash
sudo tailscale up --ssh
```

This makes the Tailscale daemon intercept port 22 on the `tailscale0` interface, enabling SSH over the Tailscale IP.

## 4. SSH Key Auth for Remote Model Switching

If you want to control llama-server services from the client machine (start/stop services remotely), set up SSH key auth:

**From client → server:**
```bash
# Copy client's public key to server
ssh-copy-id user@server-lan-ip

# Create SSH config entry on client (~/.ssh/config)
Host my-server
    HostName 192.168.1.50
    User rurouni
    IdentityFile ~/.ssh/id_ed25519
    StrictHostKeyChecking accept-new
```

## 5. Model ID Discovery

The model ID in `opencode.json` must match what the server reports:

```bash
# On client machine, probe the remote server
curl http://192.168.1.50:8081/v1/models

# The "id" field in the response is what you put in the config.
# For llama.cpp, the model ID is the GGUF filename.
```