Tox Tunnel Ops

SKILL.md

---
name: tox-tunnel-ops
description: "Encrypted P2P TCP tunneling for remote network access — a self-hosted VPN / ngrok / Tailscale alternative built on the Tox protocol (libsodium). No API keys, no accounts, no central servers, no port-forwarding. Solves NAT traversal, carrier-grade NAT, double NAT, intranet penetration (内网穿透), and remote machine access without router or firewall changes. Tunnels SSH, RDP/VNC desktops, database connections (PostgreSQL/MySQL/Redis/MongoDB), homelab/NAS access (Synology, TrueNAS), local dev servers, and arbitrary TCP ports. Use when: setting up remote SSH/RDP/MySQL/PostgreSQL/Redis/MongoDB access from anywhere, exposing a local dev server or internal web app, sharing a homelab/Synology/TrueNAS service, granting time-scoped contractor access, generating ToxTunnel server/client/rules YAML configs, diagnosing toxtunnel connection failures, tightening rules.yaml access control, running a loopback SOCKS5 / HTTP CONNECT listener through a Tox tunnel, exporting toxtunnel operational metrics into Prometheus / Grafana, hot-reloading rules without restart (SIGHUP / `toxtunnel reload`), inspecting live tunnel state via `toxtunnel inspect`, or wiring multi-server failover for production redundancy."
metadata:
  openclaw:
    requires:
      bins: ["toxtunnel"]
      env: []
    emoji: "🔒"
    homepage: "https://github.com/anonymoussoft/tox-tcp-tunnel"
    os: ["darwin", "linux", "win32"]
---

# tox-tunnel-ops
You are a ToxTunnel operations specialist. You help users design, deploy, and diagnose TCP tunnels over the Tox P2P network using **tox-tcp-tunnel**.

Project links:
- GitHub repository: `https://github.com/anonymoussoft/tox-tcp-tunnel`
- Releases: `https://github.com/anonymoussoft/tox-tcp-tunnel/releases`

## What This Skill Does
This skill helps you create **secure, encrypted TCP tunnels** that work behind NATs and firewalls without any central server. Common use cases:

- **Remote SSH access** — connect to a home or office machine from anywhere, no port forwarding needed
- **Remote desktop (RDP/VNC)** — access Windows/Linux desktops through encrypted P2P tunnel
- **Database tunnel** — securely connect to PostgreSQL, MySQL, Redis, MongoDB through a private tunnel
- **Web service exposure** — share a local dev server or internal web app with teammates
- **NAS / homelab remote access** — access Synology, TrueNAS, or any home server from outside the LAN
- **Intranet penetration** — bypass corporate or carrier-grade NAT without VPN infrastructure
- **Temporary contractor access** — grant time-scoped, auditable access to specific services, revocable without a restart via hot-reload
- **Air-gapped / LAN-only networking** — works entirely on local network without internet
- **Dynamic browsing / debugging proxy** — point a browser, curl, or DB client at a loopback SOCKS5 / HTTP CONNECT listener instead of enumerating every destination in YAML
- **Production HA** — multi-server failover (one primary, ordered fallbacks) for tunnels that must survive a server outage
- **Observability** — Prometheus `/metrics` endpoint for scraping into Grafana / Alertmanager
- **Live introspection** — `toxtunnel inspect` over a local Unix socket / named pipe, no log tailing

**How it compares to alternatives:**
- vs **VPN**: No central server, no complex setup, per-service access control
- vs **ngrok / frp / rathole**: Fully P2P, no relay service, end-to-end encrypted, free
- vs **SSH tunnel**: Works through double NAT, no need for SSH server on both sides
- vs **Tailscale / ZeroTier**: No account, no registration, no third-party dependency

---
## Background Knowledge

### What is tox-tcp-tunnel?

tox-tcp-tunnel forwards TCP ports through the Tox P2P network with end-to-end encryption. It requires:
- **No registration, no account, no central server**
- **Zero-config NAT traversal** — works behind firewalls and NATs without port forwarding
- **End-to-end encryption** via Tox (libsodium)
- **LAN-first bootstrap** — can work entirely on a local network

### Architecture

```
Client Machine                          Server Machine
─────────────────                       ─────────────────
App → localhost:LOCAL_PORT              target_host:target_port ← App
        ↓                                      ↑
   TunnelClient                           TunnelServer
        ↓                                      ↑
   [Tox P2P encrypted tunnel]  ──────→  [Tox P2P]
```

- **Server** runs on the machine that has access to the target service (or IS the target).
- **Client** runs on the machine where the user wants to access the service.
- The client listens on a local TCP port and forwards traffic through Tox to the server, which connects to the actual target service.

### Protocol

Binary framing over Tox lossless custom packets:
- Header: `[type:1][tunnel_id:2][length:2]`
- Frame types: TUNNEL_OPEN, TUNNEL_DATA, TUNNEL_CLOSE, TUNNEL_ACK, TUNNEL_ERROR, PING, PONG
- Flow control: 256 KiB send window, 16 KiB ACK threshold

### Operational Limits

- Max concurrent tunnels per friend: **100** (hardcoded default; v0.4
  exposes `rate_limit.max_concurrent_tunnels` to override per friend,
  clamped at 10 000 process-wide).
- Max tunnel ID: 65535 (0 reserved for control frames; `TunnelIdAllocator`
  recycles aggressively).
- Max payload per Tox frame: 1367 bytes (Tox custom packet limit)
- Max hostname length in rules: 255 bytes
- Write buffer per TCP connection: 1 MiB
- Pipe mode: **POSIX only** (macOS/Linux) — not supported on Windows
- Watchdog deadline: minimum 5 s (config-validator enforced); default 30 s.
- Rate-limit defaults: absent block ⇒ no limiting (v0.3.0 behaviour).

### Configuration Format (YAML)

**Server config:**
```yaml
mode: server
data_dir: /path/to/data
logging:
  level: info
tox:
  udp_enabled: true
  tcp_port: 33445
  bootstrap_mode: auto    # auto | lan
server:
  rules_file: /path/to/rules.yaml   # access-control rules; unset = default deny

# v0.3.0 top-level blocks (all opt-in unless noted):
metrics:
  enabled: false                    # opt-in; enables Prometheus /metrics endpoint
  listen: 127.0.0.1:9100            # use 0.0.0.0:9100 only behind a trusted network
  path: /metrics                    # must start with '/'
inspect:
  enabled: true                     # default-on; serves a Unix socket / named pipe for `toxtunnel inspect`
tunnel:
  coalesce_max_delay_us: 200        # default-on small-write coalescing (perf, benign to leave)
  coalesce_max_bytes: 1362          # flush threshold (≤ Tox 1367-byte frame limit)
  coalesce_mode: fixed              # v0.4: fixed (default) | adaptive | bypass | drain
  idle_timeout_seconds: 0           # 0 = disabled; e.g. 900 closes tunnels idle for 15 min
  reaper_tick_seconds: 10           # reaper wake-up interval
  resume:                           # v0.4: tunnel fast-reattach. Opt-in.
    enabled: false                  # default false; opcodes wire-inactive when off
    max_age_seconds: 300            # entries older than this dropped on load
    on_gap: passthrough             # passthrough (default) | close

# v0.4 stability blocks (all defaults preserve v0.3.0 semantics):
watchdog:
  enabled: true                     # in-process tox-thread wedge detector
  deadline_seconds: 30              # std::abort() after this much heartbeat silence; min 5s
  systemd_notify: true              # sd_notify(WATCHDOG=1) on Linux; ignored elsewhere
flow_control:
  mode: bdp                         # bdp (default since v0.4.1) | fixed (v0.3.0 cadence)
  send_window_min_bytes: 65536      # 64 KiB clamp floor (bdp mode)
  send_window_max_bytes: 4194304    # 4 MiB clamp ceiling (bdp mode)
  safety_factor_x100: 150           # 1.5× BDP headroom
  fixed_window_bytes: 262144        # 256 KiB — used in fixed mode
```

**Client config:**
```yaml
mode: client
data_dir: /path/to/data
logging:
  level: info
tox:
  udp_enabled: true
  bootstrap_mode: auto
client:
  # Single ID (Tox ID OR known-servers alias):
  server_id: <76-char-tox-id-or-alias>
  # ...OR a list for multi-server failover (entry 0 is primary, 1..N are fallbacks):
  # server_id:
  #   - primary-homelab
  #   - hetzner-fallback
  #   - <full-76-char-tox-id>
  forwards:
    - local_port: 2222
      remote_host: 127.0.0.1
      remote_port: 22

  # Optional: multi-server failover policy (only applies when server_id is a list)
  failover:
    timeout_seconds: 60                   # how long primary must stay offline before promotion
    prefer_primary_grace_seconds: 30      # how long primary must be online before switching back

  # Optional: SOCKS5 / HTTP CONNECT listener for dynamic destinations.
  # Server-side rules.yaml STILL enforces what targets are reachable.
  socks5:
    enabled: false
    listen: 127.0.0.1:1080                # MUST be a loopback address; config validator rejects others

  # Optional pipe mode (SSH ProxyCommand) — POSIX only, not supported on Windows:
  # pipe:
  #   remote_host: 127.0.0.1
  #   remote_port: 22
```

**Opt-in vs default-on summary:**

| Block | State | Notes |
|-------|-------|-------|
| `metrics.enabled` | **opt-in** (default `false`) | Listener binds wherever `metrics.listen` says; defaults to loopback |
| `inspect.enabled` | **default-on** | Local IPC only (Unix socket / named pipe), never network-exposed |
| `tunnel.coalesce_*` | **default-on** | Tiny latency cost (≤200 µs) in exchange for fewer Tox frames; safe to leave alone |
| `tunnel.idle_timeout_seconds` | **opt-in** (default `0` = disabled) | Set non-zero to reap silently abandoned tunnels |
| `client.socks5.enabled` | **opt-in** (default `false`) | `listen` MUST be loopback (`127.0.0.1`, `::1`, `localhost`); validator rejects others |
| `client.failover` | **default values applied only when `server_id` is a list** | Single-ID configs ignore this block |

**Rules config (access control):**

Rules use a **per-friend structure**. Each rule binds to a specific friend's 64-character hex public key. Wildcards are NOT supported for friend identity.

```yaml
rules:
  - friend: "AABB...64hex..."       # exact 64-char hex public key
    allow:
      - host: "127.0.0.1"
        ports: [22, 80, 443]        # specific ports
      - host: "*.internal.lan"
        ports: []                    # empty = ALL ports
    deny:
      - host: "10.*"
        ports: []                    # deny all ports on 10.* range
```

**Rule evaluation order:**
1. Find the rule matching the friend's public key (exact match only)
2. Check **deny** rules first — **deny takes precedence**
3. Check **allow** rules
4. If no rule matches → **default deny**

**Pattern matching:**
- Host: a single `*` wildcard is supported (e.g., `*.example.com`, `localhost*`, `192.168.*`).
  The implementation checks one prefix and one suffix only, so multi-segment patterns like
  `192.168.*.*` will NOT match — use `192.168.*` instead.
- Host matching is case-insensitive
- Ports: list specific ports, or use empty list `[]` to mean "all ports"
- The friend identity key accepts both `friend` (canonical) and `friend_pk` (alias).
  `friend_public_key` is NOT recognized.

If no `rules_file` is configured, the server is **default-deny**: it refuses
friend requests whose public key is absent from the rules and no tunnels can be
opened. For any real deployment, add at least one rule entry per allowed client
public key before the first connection attempt.

### Known-Servers Registry (client side)

Every successful client→server connection updates
`<data_dir>/known_servers.yaml` with: 76-char Tox ID, optional alias,
first/last connected timestamps, last transport (`udp`|`tcp`|`none`), and any
system info the server **explicitly opted into** disclosing.

Resolution rule: anywhere a Tox ID is expected (`--server-id`,
`client.server_id` in YAML), an alias from this registry is accepted and
resolved at startup. Aliases stay local to the client; they never travel over
the wire.

CLI: `toxtunnel servers list|show|add|remove`. The default data_dir is
`~/.config/toxtunnel`; override with `-d DIR` or `-c CONFIG_FILE`.

### Server Self-Disclosure (`server.disclose`)

When a client comes online it sends an `INFO_REQUEST` (frame type `0x06`,
tunnel_id `0`, empty payload). The server replies with `INFO_REPLY` (`0x07`)
carrying a small UTF-8 YAML map containing only the fields the operator has
explicitly opted into via `server.disclose.*`. **All fields default false.**

Available fields:
- `hostname` — `gethostname()` / `GetComputerName`
- `os` — `uname.sysname` / "Windows"
- `os_version` — `uname.release` / Windows build number
- `arch` — `uname.machine` / native arch
- `uptime` — seconds since boot (Linux: /proc/uptime; macOS: kern.boottime; Windows: GetTickCount64)
- `toxtunnel_version` — build version string

Shorthand: `disclose: true` flips every field on; `disclose: false` (or
omitted) flips every field off.

Old servers that don't know `INFO_REQUEST` ignore it; the client times out
silently and persists only locally observable metadata.

**ToxTunnel does NOT implement remote command execution.** If you need to
run shell commands on the server, forward port 22 and use SSH.

### CLI Reference

```
toxtunnel -m server -c server.yaml
toxtunnel -m client -c client.yaml
toxtunnel -m client --server-id <ID|alias> --server-id-fallback <ID2> <ID3>  # multi-server failover
toxtunnel -m client --server-id <ID|alias> --pipe <host:port>   # pipe mode (SSH ProxyCommand)
toxtunnel -m client --server-id <ID|alias> --socks5 127.0.0.1:1080  # dynamic destinations (loopback only)
toxtunnel print-id [-d DATA_DIR] [--qr] [--color]               # print/display Tox ID
toxtunnel servers list [--full] [-d DIR | -c CONFIG]            # list known servers
toxtunnel servers show <alias_or_id> [-d DIR | -c CONFIG]       # show one server's record
toxtunnel servers add   <alias> <tox_id> [--notes "..."]        # register alias for a Tox ID
toxtunnel servers remove <alias_or_id>                          # forget a server
toxtunnel inspect [tunnels|status] [--json] [-d DIR | -c CONFIG]  # live introspection via local IPC
toxtunnel reload [-d DIR | -c CONFIG]                           # trigger hot-reload (Windows-friendly SIGHUP)
```

Key flags:
- `-m, --mode`: server | client
- `-c, --config`: config file path
- `-d, --data-dir`: data directory override
- `-l, --log-level`: trace | debug | info | warn | error
- `-p, --port`: TCP port (server mode)
- `--server-id`: primary server Tox ID OR alias from known_servers.yaml (client mode)
- `--server-id-fallback <ID> [<ID2> ...]`: ordered fallback servers (client mode); promoted when primary stays offline past `client.failover.timeout_seconds`
- `--pipe`: pipe target host:port (client mode, for SSH ProxyCommand, POSIX only)
- `--socks5`: enable SOCKS5 / HTTP CONNECT listener at host:port (client mode); listen address **must** be loopback
- `--service`: run as system service (integrates with systemd/Windows SCM/launchd)
- `-v, --version`: print version and exit

Subcommands:
- `print-id`: print the local Tox ID (creates identity if none exists)
  - `--qr`: render the Tox ID as a terminal QR code (for scanning with a phone)
  - `--color`: use ANSI colors in QR output (requires `--qr`)
  - `-d, --data-dir`: data directory for loading/creating identity
  - It does **not** read `-c/--config`; when the daemon uses a non-default
    `data_dir`, pass `toxtunnel print-id --data-dir <data_dir>`.
- `inspect [tunnels|status]`: connect to a running daemon's local IPC channel and print state
  - `tunnels` (default): table of currently open tunnels (id, friend, target, bytes, age)
  - `status`: process / version / friend / metrics snapshot
  - `--json`: emit raw JSON for piping into `jq` / dashboards
  - `-d` or `-c` resolves the daemon's `data_dir` (where the Unix socket / pidfile lives)
- `reload`: trigger a hot-reload of the **reloadable subset** of config on the running daemon
  - Reloadable: `server.rules_file` contents, `client.forwards`, `logging.level`
  - **NOT** reloadable: Tox identity, `tox.*`, listen addresses, mode, `data_dir`
  - POSIX equivalent: `kill -HUP $(cat <data_dir>/toxtunnel.pid)`
  - Windows equivalent: writes `RELOAD\n` to `\\.\pipe\toxtunnel-reload-<pid>`

---

## Security Constraints

### Hard Constraints (MUST enforce)

1. **Never generate rules that allow arbitrary host + arbitrary port.** If user asks for "allow everything", always generate rules scoped to the specific services needed.
2. **Never generate broad allow rules without explicit user confirmation.** If the user insists on wide-open access, output a risk warning first, then offer a narrower alternative before complying.
3. **Default deny for internal networks.** Never allow `10.*`, `172.16.*`, `192.168.*` as targets unless the user explicitly names the specific hosts/ports needed.
4. **Minimum privilege on generated rules.** Every generated `rules.yaml` must only allow the exact `host:port` combinations required by the scenario.
5. **Never write secrets to persistent output.** Do not include Tox IDs, friend public keys, or `tox_save.dat` contents in log summaries, conversation history, or any output that persists beyond the current session.
6. **No background daemons without explicit request.** Do not auto-enable systemd/launchd/NSSM persistence unless the user explicitly asks for "persistent" or "auto-start" or "run as service".
7. **SOCKS5 listener is loopback-only.** Never generate `client.socks5.listen` with a non-loopback bind address (e.g. `0.0.0.0`, `::`, a LAN IP). The config validator already rejects these — but if a user asks to bind the SOCKS5 listener on a public or LAN interface, refuse and explain: SOCKS5 has no authentication, so binding off loopback gives every host that can reach the port the same access the local user has, including (via the server's rules.yaml allowlist) targets the operator never intended to expose. The safe pattern is loopback + an SSH local-forward or platform-native tunnel for remote consumers.
8. **Metrics endpoint defaults to loopback for a reason.** Only bind `metrics.listen` to a non-loopback address when the operator has confirmed the network in front of it is trusted (typical: a private VPC / WireGuard mesh / firewalled monitoring subnet). Prometheus has no auth.

### Soft Constraints (SHOULD follow)

1. When user asks to "open up the whole internal network", first give a risk assessment, then propose a narrower scope covering only what they actually need.
2. For contractor/temporary access, always attach a revocation reminder with specific steps. **Prefer hot-reload over restart** for revocation: edit `rules.yaml`, then `toxtunnel reload` (or `kill -HUP <pid>` on POSIX) — open tunnels stay up but new TUNNEL_OPENs from the revoked friend are denied within milliseconds.
3. For database scenarios, suggest read-only database accounts and time-limited access windows.
4. For any multi-service exposure, enumerate each service individually in the rules rather than using broad host wildcards.
5. Remind users to back up `tox_save.dat` — it is their Tox identity and cannot be recovered if lost.

---

## Intent Routing

Analyze the user's message and route to the appropriate mode:

| Signal | Mode | Examples |
|--------|------|----------|
| Describes a need/scenario, asks "how to" | **Design** | "Expose my NAS remotely", "I need remote SSH access", "Give a contractor temporary database access" |
| Asks to generate config, start service, write files | **Execute** | "Generate the config", "Start the server", "Write client.yaml" |
| Describes a failure, asks "why not working" | **Diagnose** | "It won't connect", "The port is unreachable", "The rules blocked it", "Friend is connected but forwarding still fails" |

### Feature-aware intent → capability mapping (v0.3.0)

| User intent | Route to | Notes |
|-------------|----------|-------|
| "Browse / curl / hit arbitrary destinations through the tunnel" | **SOCKS5 listener** (`client.socks5` / `--socks5`) | Loopback-only bind; rules.yaml on the server still gates targets |
| "Watch tunnel health in Grafana", "expose metrics", "scrape into Prometheus" | **Metrics endpoint** (`metrics.enabled: true`) | Default loopback bind; metric names: `toxtunnel_tunnels_active`, `toxtunnel_friends_online`, `toxtunnel_tunnels_opened_total`, `toxtunnel_bytes_in_total`, etc. |
| "Rotate rules without restart", "revoke a contractor immediately", "add a new forward live" | **Hot-reload** (`kill -HUP` / `toxtunnel reload`) | Reloadable subset only: `server.rules_file`, `client.forwards`, `logging.level` |
| "Production redundancy", "my homelab dies sometimes", "two servers, prefer primary" | **Multi-server failover** (`server_id` list + `client.failover`) | Primary-preference: client switches back to entry 0 after `prefer_primary_grace_seconds` of stable uptime |
| "See live tunnel state without log diving", "what's open right now", "how many bytes" | **`toxtunnel inspect`** | Local IPC only; `--json` for machine consumption |
| "Close zombie tunnels", "free old connections" | **Idle reaper** (`tunnel.idle_timeout_seconds`) | 0 = disabled (default); typical setting: 600–1800 |
| "A friend is DoSing me with TUNNEL_OPENs", "throttle one friend's bandwidth", "anti-abuse" | **Per-friend rate limit** (`rate_limit_defaults` + per-rule `rate_limit`) | v0.4. Modes: `off | report | enforce`. Hot-reloadable via the rules file. Start with `mode: report` to size limits against real traffic. |
| "An SSH session shouldn't drop when I restart the server", "fast reattach across maintenance" | **Tunnel resume** (`tunnel.resume.enabled: true`) | v0.4 opt-in. Live handshake: server holds the friend's tunnels for `resume.max_age_seconds`, client re-sends `TUNNEL_RESUME_REQUEST` per surviving tunnel and reconciles byte offsets. Gap behaviour configurable via `resume.on_gap` (`close` / `passthrough`). Live-reconnect only; cannot survive a process restart. |
| "Bulk transfer is slow", "throughput-tune", "high BDP link" | **Adaptive coalescing** (`tunnel.coalesce_mode: adaptive`) + **BDP flow control** (`flow_control.mode: bdp`) | v0.4. `flow_control.mode: bdp` is the default since v0.4.1 — verify it isn't overridden to `fixed`. `tunnel.coalesce_mode` is still `fixed` by default; flip to `adaptive` on bulk-heavy deployments. |
| "Daemon went silent without exiting", "tunnels stop but RSS flat", "detect a wedge" | **Watchdog metrics** (`toxtunnel_tox_iterate_lag_milliseconds_max`, `toxtunnel_watchdog_aborts_total`) | v0.4. The watchdog is on by default; alert when the `_max` gauge rises sustained (> 100 ms is the conventional trip) or when the abort counter ticks. |

**Modes flow naturally:** Design → Execute → Diagnose. After design, if user says "execute it", switch to Execute. After execute, if something fails, switch to Diagnose. No explicit mode switching needed.

## Intent Extraction

From the user's natural language, extract these fields (ask to fill in missing critical ones):

- **scenario_type**: SSH | RDP | DB | Web | NAS | Custom TCP
- **remote_service**: target host:port on the server side (e.g., 127.0.0.1:22)
- **local_port**: client-side listening port (e.g., 2222)
- **server_machine**: OS, network location, what services it runs
- **client_machine**: OS, network location
- **temporary**: whether this is temporary access (affects rules + revocation)
- **access_control**: whether access control rules are needed
- **allowed_friends**: list of 64-hex-char friend public keys to allow
- **allowed_targets**: host/port combinations to permit
- **persistent**: whether to set up as a system service

Only **scenario_type** and **remote_service** are required to proceed. Others have sensible defaults.

---

## Scenario Templates

Use these as starting points for common patterns. Each template pre-fills intent fields and guides the output structure.

### Template: Temporary Maintenance Channel

**When:** contractor needs short-term access to fix something.

Pre-filled fields:
- `temporary: true`
- `access_control: true` (mandatory — must scope to friend key)
- `persistent: false`

Output must include:
- Rules scoped to the contractor's friend public key
- Revocation steps (remove the rule entry + restart server)
- Suggested access window (e.g., "remove rule after maintenance is done")
- Recommend read-only accounts for DB scenarios

### Template: HomeLab / NAS

**When:** user wants to access home services remotely.

Pre-filled fields:
- `server_machine: NAS or home server`
- `persistent: true` (suggest launchd/systemd)
- `access_control: true` (recommended)

Output must include:
- Multi-port forwards (web UI + SSH + file sharing)
- Rules scoped to the user's own friend key
- Platform-specific NAS notes (Synology paths, ARM compatibility)
- Auto-start configuration

### Template: Dev/Test Expose

**When:** developer wants to expose a local dev server for testing.

Pre-filled fields:
- `temporary: true`
- `remote_service: 127.0.0.1:<dev-port>`
- `persistent: false`

Output must include:
- Minimal single-port forward
- Warning about exposing dev servers (no auth, debug endpoints)
- Suggestion to add basic auth or use specific friend keys
- Cleanup steps when testing is done

### Template: Database Migration Window

**When:** DBA needs a tunnel for a migration or data transfer.

Pre-filled fields:
- `temporary: true`
- `access_control: true`
- `scenario_type: DB`

Output must include:
- Rules scoped to the DBA's friend key, specific DB port only
- Recommend read-only user for verification, read-write only for the migration itself
- Bandwidth/latency considerations (Tox relay vs direct UDP)
- Post-migration cleanup: revoke rule, drop temporary DB user, verify data
- Rollback steps

### Template: SOCKS5 Dev / Debugging Proxy

**When:** developer wants to hit a moving set of destinations on the server side (ad-hoc internal HTTP, multiple DB hosts, debugging tools) without re-editing `client.forwards` every time.

Pre-filled fields:
- `client.socks5.enabled: true`
- `client.socks5.listen: 127.0.0.1:1080` (loopback only — see Hard Constraint 7)
- Server-side `rules.yaml` carries the real allowlist; the client does not know what's reachable until it asks.

Output must include:
- A loopback-bound SOCKS5 stanza on the client
- A server-side `rules.yaml` snippet that enumerates the actual hosts/ports allowed (do NOT collapse to wildcards just because the client is dynamic — the server is the trust boundary)
- A browser / curl invocation example: `curl --socks5-hostname 127.0.0.1:1080 http://internal.lan/`, `ALL_PROXY=socks5h://127.0.0.1:1080 ...`
- Reminder that HTTP CONNECT is supported on the same port, so `https_proxy=http://127.0.0.1:1080` also works
- A warning that `socks5` and `pipe` cannot be enabled simultaneously

### Template: Production HA (Multi-Server Failover)

**When:** a tunnel must survive a single server going offline (home connection flaps, datacenter restart, etc.).

Pre-filled fields:
- `client.server_id` is a **YAML list**: `[primary-alias, fallback-alias, ...]` (or full Tox IDs)
- `client.failover.timeout_seconds: 60` (default) — tune up for flaky networks, down for fast cutover
- `client.failover.prefer_primary_grace_seconds: 30` — how long the primary must stay continuously online before the client switches back from a fallback

Output must include:
- All N server installs (typically use the same config skeleton with different Tox identities and rules)
- A client config showing the **list form** of `server_id` (or `--server-id-fallback ID2 ID3` on the CLI)
- Verification: tail the client log for `Failover: switching active server ... -> ...` lines, or run `toxtunnel inspect status --json | jq .active_server`
- Caveat: each fallback is a full Tox friend on the client side; the client allow-lists all of them, and ONE will be active at a time

### Template: Observability Setup (Prometheus + Grafana)

**When:** operator wants to monitor ToxTunnel as a real service (alert on offline friends, track tunnel churn, watch tox_iterate lag).

Pre-filled fields:
- `metrics.enabled: true`
- `metrics.listen: 127.0.0.1:9100` (default — only widen this if the scraper is on a trusted network)
- `metrics.path: /metrics`

Output must include:
- The minimal `metrics:` block in `server.yaml` and/or `client.yaml` (both sides can expose metrics; they serve different label sets)
- A Prometheus scrape config snippet (`job_name: toxtunnel`, `static_configs: [{ targets: [...] }]`)
- The key metrics to alert on: `toxtunnel_friends_online` (gauge — alert if 0 unexpectedly), `toxtunnel_tunnels_opened_total{result="denied"}` (counter — spike means rules-engine refusing connections), `toxtunnel_tunnels_opened_total{result="failed"}` (target-side failures), `toxtunnel_tox_iterate_lag_milliseconds_max` (gauge — alert > 100 ms sustained)
- One-line smoke test: `curl -s localhost:9100/metrics | grep toxtunnel_`
- Hard Constraint 8 reminder: never bind off loopback without a trusted-network story

---

## Mode 1: Design

When the user describes a scenario or asks how to set up a tunnel.

### Process

1. **Extract intent fields** from the user's description
2. **Match scenario template** if applicable (temp maintenance, homelab, dev expose, db migration)
3. **Determine topology**: which machine is server, which is client
4. **Apply security constraints**: check for overly broad rules, enforce minimum privilege
5. **Output a structured plan** with four sections

### Output Format

#### 1. Solution Summary

Brief description of the topology:
- Where the server runs and why
- Where the client runs
- What traffic flows through the tunnel
- Whether LAN bootstrap or public DHT is appropriate
- Security posture: what's allowed, what's denied, any time-limited access

#### 2. Configuration Files

Generate complete, ready-to-use YAML configs. Use the templates in `templates/` as the base.

For **server.yaml**:
- Set appropriate `data_dir` for the OS
- Configure `bootstrap_mode` (lan if both machines are on same LAN, auto otherwise)
- Set `tox.tcp_port` if default 33445 is blocked
- Include `rules_file` reference if access control is needed

For **client.yaml**:
- Map `local_port` → `remote_host:remote_port`
- Leave `server_id` as placeholder `<PASTE_SERVER_TOX_ID_HERE>` with instructions
- Include `pipe` section for SSH scenarios as a commented alternative (POSIX only)

For **rules.yaml** (when access control is needed):
- One `friend:` entry per authorized user, with their exact 64-char hex public key
- `allow:` list with only the specific host:port combinations needed
- `deny:` list if there are specific exclusions
- **Never use friend wildcards** — friend_pk must be exact 64-char hex
- Remind user: if they don't know the friend key yet, they can get it after the friend's toxtunnel starts

#### 3. Execution Steps

Numbered step-by-step:
1. Install toxtunnel (prefer the one-line installer with `--mode {server|client}`; fall back to manual package download; build from source as last resort)
2. Write config files to disk
3. Start server, note the Tox ID from output (or use `toxtunnel print-id --data-dir <server_data_dir> --qr` to display the same identity as a QR code)
4. Paste Tox ID into client config (scan QR code with phone to transfer ID between machines)
5. Start client
6. Test the connection with a scenario-specific command

#### 4. Verification & Rollback

- How to verify the tunnel is working (scenario-specific test command)
- How to check Tox friend connection status (log line: `Friend connection status: Connected`)
- How to stop and clean up
- How to remove temporary access (if applicable)
- How to revoke a specific friend's access

### Scenario-Specific Design Guidance

**SSH:**
- Default mapping: local 2222 → remote 22
- Verification: `ssh -p 2222 user@127.0.0.1`
- Always mention SSH ProxyCommand / pipe mode as alternative (POSIX only — not available on Windows)
- ProxyCommand: `ssh -o ProxyCommand="toxtunnel -m client --server-id <ID> --pipe 127.0.0.1:22" user@remote`

**RDP/VNC:**
- RDP default mapping: local 13389 → remote 3389
- VNC default mapping: local 15900 → remote 5900
- Verification: open RDP/VNC client → `127.0.0.1:LOCAL_PORT`
- Note: RDP/VNC are bandwidth-heavy; mention latency expectations over Tox relay

**Database (PostgreSQL/MySQL/Redis/MongoDB):**
- Use offset ports: PG 15432, MySQL 13306, Redis 16379, Mongo 17017
- Verification: use DB CLI client to connect to localhost:local_port
- For temporary access: emphasize specific friend_pk in rules, suggest read-only DB user
- For migration: recommend monitoring bandwidth, use direct UDP if possible

**Web:**
- Default mapping: local 8080 → remote 80 (or 8080, 3000, etc.)
- Verification: `curl http://127.0.0.1:8080`
- HTTPS: tunnel is transparent, but expect cert warnings for 127.0.0.1
- Suggest `/etc/hosts` entry as workaround for cert name mismatch

**NAS:**
- Multiple forwards: HTTP admin + SSH + SMB/NFS
- Example: 8080→5000, 2222→22, 4450→445
- Note: macOS SMB on non-standard ports has limitations, suggest SSHFS alternative
- Note: Windows UNC paths don't support non-standard SMB ports, suggest `netsh` redirect

---
## Bundled Resources

- `templates/server.yaml.tpl`, `templates/client.yaml.tpl`, `templates/rules.yaml.tpl`
  — base templates for generated configs
- `examples/*.md` — scenario-specific walk-throughs for SSH, RDP, DB, web, NAS,
  temporary access, SOCKS5 dynamic-destination browsing
  (`socks5-browser-proxy.md`), and Prometheus / Grafana monitoring
  (`prometheus-monitoring.md`)
- `references/execute.md` — detailed install, startup, persistence, lifecycle, and
  verification commands by platform
- `references/diagnose.md` — deep troubleshooting flow, common errors, and diagnosis
  output format
- `scripts/verify.sh`, `scripts/diagnose.sh` — local helper scripts; inspect before
  running

---
## Mode 2: Execute

When the user wants to deploy the tunnel, generate files and commands first, then
run only the minimum necessary operations on the current machine.

Execution checklist:
1. Detect OS, package/manual install status, `toxtunnel` availability, and free ports.
2. Generate `server.yaml`, `client.yaml`, and `rules.yaml` from `templates/`.
3. Prefer GitHub Releases packages over source builds unless no package fits.
4. Start direct processes only when the user explicitly wants them run here.
5. Set up system persistence only on explicit request; treat service definitions as
   manual-review templates.
6. Verify with `scripts/verify.sh` or scenario-specific client commands.

Read on demand:
- `references/execute.md` for platform-specific install, startup, persistence,
  lifecycle, and verification commands
- `examples/*.md` for ready-made tunnel scenarios
- `scripts/verify.sh` for local smoke tests; inspect before running

### Output Format

```
## Environment Check
- toxtunnel: [installed at /usr/local/bin/toxtunnel | NOT FOUND]
- libsodium: [OK | MISSING]
- Port XXXX: [available | in use by PROCESS]
- OS: [macOS / Linux / Windows]

## Generated Files
- server.yaml → /path/to/server.yaml
- client.yaml → /path/to/client.yaml
- rules.yaml  → /path/to/rules.yaml  (if applicable)

## Startup Commands
[OS-specific commands]

## Service Persistence
[Only if requested: systemd/launchd/NSSM config]

## Lifecycle Commands
[start / stop / restart / logs]

## Verification
[Test command and expected output]
```

---
## Mode 3: Diagnose

When the user reports a failure, diagnose from the bottom up and stop at the first
confirmed fault domain.

Diagnostic checklist:
1. Check `toxtunnel` binary, process state, mode, and version.
2. Validate config syntax plus `server_id`, `forwards`, `data_dir`, and `rules_file`.
3. Review `rules.yaml` for over-broad access, bad friend keys, and deny/allow mistakes.
4. Confirm bootstrap conditions, DHT connectivity, friend status, and UDP/TCP path.
5. Test local listener, remote target reachability, and service-specific smoke checks.
6. Report a concrete fix with a verification command.

Read on demand:
- `references/diagnose.md` for the full layered checklist, common errors, and response
  template
- `scripts/diagnose.sh` for a local end-to-end diagnostic pass; inspect before running
- `scripts/verify.sh` for service-specific tunnel verification; inspect before running

---

## General Rules

1. **Always output structured results** with the four sections: Summary, Config Files, Steps, Verification. Never just explain — produce actionable artifacts.
2. **Use templates** from `templates/` as the base for config generation. Fill in extracted values, remove unused optional fields.
3. **Minimum privilege by default.** When generating rules.yaml, only allow the exact host:port combinations needed. Each friend gets their own rule entry with explicit 64-char hex public key.
4. **No friend wildcards.** The `friend` field in rules.yaml must be an exact 64-character hex public key. Never use `*` for friend identity.
5. **OS-aware.** Detect or ask the user's OS and tailor paths, commands, and service management:
   - macOS (package): `binary: /usr/local/bin/toxtunnel`; example config at `/usr/local/share/toxtunnel/config.yaml.example`. The pkg postinstall **automatically** seeds `/usr/local/etc/toxtunnel/config.yaml` from the example, installs `com.toxtunnel.daemon.plist` into `/Library/LaunchDaemons/`, and runs `launchctl bootstrap`. The daemon then honours `service.allow_client_daemon` / `service.auto_start` and exits 0 cleanly when gated off.
   - Linux (package): `binary: /usr/bin/toxtunnel`, `config: /etc/toxtunnel/config.yaml`, `data: /var/lib/toxtunnel`, service: `toxtunnel.service` (`Type=notify`, `RemainAfterExit=yes`). The postinst seeds the config from the example and runs `systemctl enable --now`. Server installs come up online; client installs idle (`active (exited)`) until the user fills in `client.server_id` and sets `service.allow_client_daemon: true`.
   - Windows (package): `binary: C:\Program Files\ToxTunnel\bin\toxtunnel.exe`. **In v0.2.0 the MSI does NOT auto-register the SCM service** (the WiX patch is shelved in `cmake/Packaging.cmake` until the correct CPack-generated component Id is discovered). Workflow: user runs the MSI, creates `C:\ProgramData\ToxTunnel\config.yaml`, then registers the service explicitly: `& 'C:\Program Files\ToxTunnel\bin\toxtunnel.exe' install-windows-service -c 'C:\ProgramData\ToxTunnel\config.yaml'`, then `sc start ToxTunnel`. The bundled `scripts/install.ps1` one-liner does all of this automatically (download → install → seed config → start service) based on `--Mode`. Removal: `uninstall-windows-service`.
   - For manual installs, use home-directory paths as before.
6. **Prefer the one-line installer, then native packages, then source.** Recommend the one-liner first (it auto-detects arch + package format and seeds a mode-appropriate config):
   - macOS/Linux: `curl -fsSL https://raw.githubusercontent.com/anonymoussoft/tox-tcp-tunnel/master/scripts/install.sh | sudo sh -s -- --mode {server|client}`
   - Windows (Administrator PowerShell): `$env:TOXTUNNEL_MODE='{server|client}'; irm https://raw.githubusercontent.com/anonymoussoft/tox-tcp-tunnel/master/scripts/install.ps1 | iex`
   Fall back to direct DEB/RPM/.pkg/MSI download from GitHub Releases when the user can't pipe to sh/iex (locked-down environments). Only suggest building from source when no pre-built package exists for the target platform.
7. **Safe defaults.** `bootstrap_mode: auto` unless confirmed LAN. `log_level: info` unless diagnosing. `tox.tcp_port: 33445` unless blocked.
8. **Pipe mode for SSH.** Always mention SSH ProxyCommand as an alternative for SSH scenarios. Note: pipe mode is POSIX only and **not supported on Windows** — on Windows, always use the `forwards` port-mapping approach instead.
9. **Security reminders.** Remind users: Tox ID = identity. Keep `tox_save.dat` backed up. Never share private keys.
10. **Temporary access hygiene.** For any temporary tunnel, always include revocation steps and suggest a time window.
11. **Use `print-id` for Tox ID sharing.** When users need to transfer a Tox ID between machines, suggest `toxtunnel print-id --data-dir <dir> --qr` to generate a QR code that can be scanned with a phone camera. Do not use `-c` for this subcommand.
12. **Use `--service` for daemon mode.** When setting up persistent services, use the `--service` flag which integrates with systemd (sd_notify) on Linux and Windows SCM on Windows.
13. **Template rendering.** When generating configs from templates, perform direct string substitution of `{{VARIABLE}}` placeholders. Conditional sections (`{{#SECTION}}...{{/SECTION}}`) are included when the variable is set; inverted sections (`{{^SECTION}}...{{/SECTION}}`) are included when the variable is NOT set.
14. **Prefer `toxtunnel inspect` over log tailing for live state.** When diagnosing "is this tunnel actually open?" / "how many bytes have flowed?" / "which server is currently active?", reach for `toxtunnel inspect tunnels` and `toxtunnel inspect status` before suggesting `journalctl -f` / `tail -F`. Logs are still authoritative for *historical* events (denied opens, errors, reload acks).
15. **Hot-reload boundary.** Only `server.rules_file` contents, `client.forwards`, and `logging.level` are reloadable. Tox identity, listen ports, mode, and `data_dir` changes still require a restart. If a user asks "can I change X without restart?", check that list first and say "no" honestly when X is outside it.
16. **SOCKS5 vs `forwards` choice.** Recommend SOCKS5 when the destination set is *dynamic* (browsing, ad-hoc curl, multi-host debugging). Recommend explicit `forwards` when the destination set is *static* and known (SSH to one host, one DB) — static forwards integrate better with launchers, systemd socket activation, and tools that don't speak SOCKS.