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.

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

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:

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