network-tune

---
name: "network-tune"
description: "Agent-facing TCP/BBR tuning for modern Debian/Ubuntu VPS hosts over SSH. Use when Codex needs to optimize a Linux VPS given an SSH target, IP address, hostname, or root@host; install XanMod/BBR v3, apply TCP buffer/FQ/MSS/initcwnd tuning, optionally set DNS, optionally tune Realm/conntrack, optionally disable IPv6, reboot, verify persistence, or diagnose why vps-tcp-tune returns to its menu during kernel installation."
license: "MIT"
---

# Network Tune

## Goal

Tune a remote Debian/Ubuntu VPS over SSH using a compact, agent-safe TCP/BBR profile for Ubuntu 22.04/24.04-era systems. Prefer the bundled wrapper instead of manually pasting large shell functions.

## Core Command

Run from this skill directory:

```bash
scripts/agent-tcp-tune.sh --target root@HOST --bandwidth-mbps 1000 --region asia --reboot-verify
```

Use `--target root@IP` when the user gives only an IP. Use `--bandwidth-mbps` from the user's plan or provider spec; avoid relying on one automatic Speedtest result. Use `--region asia` for Singapore/HK/JP/KR and `--region overseas` for high-latency transoceanic service paths.

Options:

```text
--install-kernel              install XanMod after Agent preflight decision
--dns cloudflare|google|quad9  explicitly set systemd-resolved DNS
--realm                       apply Realm/conntrack tuning
--disable-ipv6                explicitly disable IPv6
```

The wrapper uploads:

```text
scripts/remote-tcp-tune.sh
```

to `/root/agent-tcp-tune` on the remote host.

## Workflow

1. Confirm the SSH target and expected bandwidth. If the user asks for a complete operation, reboot verification is allowed; otherwise ask before rebooting.
2. Run preflight first, then decide the plan. Use `--install-kernel` only when the user wants XanMod/BBR v3 or preflight shows the stock kernel lacks the needed BBR path.
3. If the wrapper exits `10`, it installed a kernel and stopped before reboot because `--reboot-verify` was omitted. Re-run with `--reboot-verify` or reboot manually and then run the remote `tune-66` command.
4. Report the final verification keys: kernel, congestion control, qdisc, TCP buffers, initcwnd/initrwnd, IPv6 status, optional conntrack, optional DNS, MSS clamp, and persistence service.

## Important Policy

Read `references/tuning-policy.md` when you need rationale, rollback notes, or failure handling details.

Critical defaults:

- Prefer manual `--bandwidth-mbps` over automatic Speedtest.
- Treat 1Gbps Singapore VPS as `--bandwidth-mbps 1000 --region asia`, which gives Eric's 16MB TCP buffer profile.
- Probe XanMod packages instead of hard-installing `x64v4`; many v4-capable CPUs still need v3 packages because the repository may publish only lower package levels.
- Prefer XanMod LTS packages, then mainline.
- Probe the host codename first, then `noble`, `bookworm`, and `trixie`; remove the temporary XanMod APT source after install.
- Keep kernel installation, DNS, Realm, and IPv6 changes explicit. Default tuning should change TCP/BBR behavior only.
- Inspect Realm config manually before changing routing, listen, IPv4/IPv6, or `nodelay` settings. The script handles conntrack and service limits only.
- Verify after reboot when the user permits rebooting.

## Direct Remote Commands

For manual recovery or debugging after upload:

```bash
ssh root@HOST 'bash /root/agent-tcp-tune/remote-tcp-tune.sh preflight'
ssh root@HOST 'bash /root/agent-tcp-tune/remote-tcp-tune.sh install-kernel'
ssh root@HOST 'bash /root/agent-tcp-tune/remote-tcp-tune.sh tune-66 --bandwidth-mbps 1000 --region asia'
ssh root@HOST 'bash /root/agent-tcp-tune/remote-tcp-tune.sh tune-66 --bandwidth-mbps 1000 --region asia --dns cloudflare --realm'
ssh root@HOST 'bash /root/agent-tcp-tune/remote-tcp-tune.sh verify'
```

Remote logs live in `/root/agent-tcp-tune/logs`.

## Output Standard

Keep the final report short and concrete:

```text
Kernel: 6.x-xanmod
BBR: bbr
Qdisc: fq
TCP buffer: 16MB
initcwnd/initrwnd: 32
DNS: none/cloudflare/google/quad9
Persistence: network-tune-apply enabled/active
IPv6: kept or disabled
Rollback: /root/agent-tcp-tune/backup-* and /etc/default/network-tune-dns if DNS was enabled
```