# UFW/Firewall Ports for Cross-Machine AI Tools

## Problem

When AI tools run on a server (Debian) and clients connect from another machine (CachyOS desktop), UFW on the server blocks the ports. The agent must check and open ports automatically, not assume they're reachable.

## Ports Used

| Port | Service | Default Binding | Notes |
|------|---------|-----------------|-------|
| 9292 | llama-swap | `:9292` (0.0.0.0) | Main inference proxy, MUST be open for remote clients |
| 4097 | OpenCode server | `127.0.0.1` → `0.0.0.0` with `--hostname 0.0.0.0` | Desktop connectivity |
| 18789 | Hermes Gateway | tailscale0 only | Dashboard access |
| 9119 | Hermes Dashboard | tailscale0 only | Web dashboard |
| 22 | SSH | — | Usually already open for LAN |

## Check Current State

```bash
sudo ufw status | grep <port>
```

## Add Rules

```bash
# LAN subnet
sudo ufw allow from 192.168.1.0/24 to any port <port> proto tcp

# Tailscale subnet
sudo ufw allow from 100.64.0.0/10 to any port <port> proto tcp

# Or a single IP
sudo ufw allow from 192.168.1.111 to any port <port> proto tcp
```

## Common Pitfalls

- **Default ufw policy is DROP** — any port not explicitly allowed is blocked even if the service listens on 0.0.0.0
- **llama-swap listens on `:9292` (all interfaces)** but ufw may only allow 127.0.0.1. Always check: `sudo ufw status | grep 9292`
- **After adding rules, test from the client:** `curl -s --max-time 10 http://<server-ip>:<port>/v1/models`
- **The agent should check ufw rules before declaring connectivity works** — connection timeout from a remote machine is almost always a firewall issue, not a service issue