| 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. |
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:
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:
--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:
scripts/remote-tcp-tune.sh
to /root/agent-tcp-tune on the remote host.
Workflow
- Confirm the SSH target and expected bandwidth. If the user asks for a complete operation, reboot verification is allowed; otherwise ask before rebooting.
- 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.
- 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.
- 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:
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:
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
