Easy userspace bandwidth manager for Linux
oxy is a CLI tool written in Rust that provides an easy-to-use interface for monitoring, limiting, and shaping per-process network bandwidth on Linux. It leverages Linux traffic control (tc) with HTB qdisc, nftables for marking, and cgroup v2 for rate limiting. The ss utility is used for real-time bandwidth monitoring, and a built-in TUI dashboard provides a live, htop-like experience for network traffic.
- Monitor bandwidth usage per process/program with cumulative and real-time rates
- Limit download and/or upload speeds per process with tc + nftables + cgroup v2
- QoS priority shaping — assign high/low priority tiers instead of hard limits
- TUI dashboard — live bandwidth monitor with sparklines, scrolling, and dual RX/TX graphs
- Auto-throttle daemon — background mode that auto-limits when thresholds are exceeded
- Watch & alert — background monitor with desktop notifications on bandwidth thresholds
- Bandwidth profiles — save, load, and apply named bandwidth limit presets
- Bandwidth logging — snapshot and review historical bandwidth usage
- Shell completions — bash, zsh, fish, elvish, powershell
- Man page generation — roff format for system manual installation
- Interface management — auto-detect or explicitly specify network interfaces
- Strict CLI validation — invalid commands, interfaces, and values are rejected with clear errors
- Supports multiple bandwidth units:
byte/bs,kb,mb,gb,kbit,mbit,gbit - Built-in presets:
gaming,streaming,background - Clean, colored terminal output (respects
NO_COLOR) - JSON output mode for scripting integration
- Persistent state across invocations (survives restarts)
- Linux (kernel 5.4+ recommended for full cgroup v2 support)
- Root privileges (for bandwidth limiting, QoS, and auto-throttle operations)
- iproute2 package (provides
tcandipcommands) - nftables (for packet marking on download limiting)
- Rust 1.88+ (for building from source)
Download the latest release from GitHub Releases:
# Download and extract
curl -sL https://github.com/oxyzenq/oxy/releases/latest/download/oxy-v2.0.0-x86_64-linux.tar.gz | tar xz
# Install system-wide
sudo install -Dm755 oxy-v2.0.0-x86_64-linux/oxy /usr/local/bin/oxyVerify the download with SHA256 checksums published alongside each release.
git clone https://github.com/oxyzenq/oxy.git
cd oxy
cargo build --release
# Install system-wide
sudo install -Dm755 target/release/oxy /usr/local/bin/oxycargo build --release
sudo install -Dm755 target/release/oxy /usr/local/bin/oxy# Bash
oxy completions bash | sudo tee /usr/share/bash-completion/completions/oxy > /dev/null
# Zsh
oxy completions zsh > ~/.zsh/completions/_oxy
# Fish
oxy completions fish > ~/.config/fish/completions/oxy.fishoxy [FLAGS] [COMMAND] [ARGS]
FLAGS:
-i, --info Print detailed package information
-v, --ver Print version (short)
-V, --version Print version (long)
--help-all Show comprehensive help with all commands and examples
--iface [INTERFACE] Specify network interface (no value = list available)
--no-color Disable colored output
COMMANDS:
list List network bandwidth usage per process
strict Set bandwidth limits for a process
unstrict Remove all bandwidth limits
status Show active bandwidth limits
clean Clean up orphaned bandwidth limits
profile Manage named bandwidth profiles
qos QoS priority-based bandwidth shaping
watch Monitor and alert on bandwidth threshold
auto Auto-throttle daemon mode
log Bandwidth usage history
backend Show backend and eBPF support status
completions Generate shell completions
man Generate man page
Show all programs/ports with active bandwidth usage:
# List all processes with bandwidth usage (default)
oxy list
# Real-time TUI dashboard (like htop for network)
oxy list --live
# Live mode with custom refresh interval (2 seconds)
oxy list --live --interval 2
# Sort by highest to lowest bandwidth usage
oxy list --high-to-low-usage-net
# Show individual socket connections per process
oxy list --verbose
# Output as JSON for scripting
oxy list --jsonApply download and/or upload speed limits to a specific process:
# Limit both download and upload
sudo oxy strict -d 500kb -u 500kb brave
# Limit only download (omit -u)
sudo oxy strict -d 1mb firefox
# Limit only upload (omit -d)
sudo oxy strict -u 250kb 1234
# Limit by PID
sudo oxy strict -d 1mb -u 1mb 8100
# Use a preset profile
sudo oxy strict --preset gaming discord
sudo oxy strict --preset background steam
sudo oxy strict --preset streaming zoomNote: PID 0 (kernel idle thread) and user names (e.g.,
root) cannot be limited. oxy targets processes by PID or binary name. PID 0 is not a userspace process and has no network sockets or cgroup association.
Re-limiting without unstrict first is supported — old rules are auto-cleaned:
sudo oxy strict -d 500kb brave # apply limit
sudo oxy strict -d 10mb brave # auto-overrides to 10mbRemove all bandwidth restrictions from a process:
# By process name
sudo oxy unstrict brave
# By PID
sudo oxy unstrict 8100oxy statusRemove tc/cgroup rules for processes that have already exited:
sudo oxy cleanAuto-detect is used by default. Explicitly specify an interface with --iface:
# List available interfaces
oxy --iface
# Use a specific interface for any command
oxy --iface wlan0 list --live
sudo oxy --iface eth0 strict -d 1mb brave
sudo oxy --iface enp3s0 qos high firefoxAssign priority tiers instead of hard limits. High priority processes get bandwidth first; idle bandwidth from low-priority processes redistributes automatically:
# High priority for browser
sudo oxy qos high brave
# Low priority for download manager
sudo oxy qos low wget
# Show current QoS assignments
oxy qos status
# Clear all QoS rules
sudo oxy qos resetSave and load custom bandwidth profiles:
# Save a profile
oxy profile save slow --dl 50kb --ul 50kb
oxy profile save streaming --dl 5mb --ul 2mb
# Apply a profile
sudo oxy profile apply slow steam
# List all profiles
oxy profile list
# Delete a profile
oxy profile delete slowMonitor a process and send a desktop notification when bandwidth exceeds a threshold:
# Alert when wget rate exceeds 500KB/s
oxy watch -a 500kb wget
# Check every 30 seconds
oxy watch -a 5mb firefox -i 30Continuously monitor and automatically apply limits when thresholds are exceeded:
# Auto-limit when download exceeds 100MB/s and upload exceeds 50MB/s
sudo oxy auto --download 100mb --upload 50mb
# Kill heavy processes instead of limiting
sudo oxy auto --download 80mb --kill firefox
# Run as a background daemon
sudo oxy auto --daemonRecord and review historical bandwidth usage:
# Show recent history
oxy log
# Record a snapshot of current state
oxy log --snapshot
# Show last hour
oxy log --last 1h
# JSON output for analysis
oxy log --jsonBuilt-in presets for common use cases:
| Preset | Download | Upload | Use Case |
|---|---|---|---|
gaming |
50 mb/s | 50 mb/s | Low latency, prioritizes responsive gameplay |
streaming |
10 mb/s | 5 mb/s | Balanced for video calls and streaming |
background |
500 kb/s | 100 kb/s | Minimal bandwidth for background downloads |
| Unit | Description | Example |
|---|---|---|
b, byte, bs |
Bytes per second | 100bs, 500byte |
kb, kbs |
Kilobytes per second (1 KB = 1024 B) | 500kb, 2kbs |
mb, mbs |
Megabytes per second (1 MB = 1024 KB) | 1mb, 50mbs |
gb, gbs |
Gigabytes per second (1 GB = 1024 MB) | 1gb, 2gbs |
kbit, kbits |
Kilobits per second | 100kbit, 500kbits |
mbit, mbits |
Megabits per second | 10mbit, 100mbits |
gbit, gbits |
Gigabits per second | 1gbit |
Note: Minimum rate is 1 KB/s (1024 B/s). Values below this are rejected because the Linux kernel's HTB scheduler cannot accurately enforce sub-KB/s rates due to clock tick granularity.
oxy works by combining several Linux kernel features:
Uses the ss (socket statistics) command to discover all active TCP/UDP sockets on the system, maps them to their owning processes via /proc filesystem, and extracts per-socket byte counters (available on kernels 4.6+).
Uses a layered approach:
- HTB qdisc — Hierarchical Token Bucket queueing discipline provides the rate-limiting mechanism
- Traffic classes — Each limited process gets its own tc class with configurable rate/ceil
- Cgroup v2 — Tags traffic originating from specific processes using socket cgroupv2 classification
- nftables — Marks packets in prerouting for download (ingress) direction
- tc filters — Routes tagged traffic to the appropriate class for enforcement
Upload (egress)
┌─────────────┐ ┌──────────────┐ ┌────────────────┐
│ Process │────>│ Cgroup v2 │────>│ socket │
│ (PID) │ │ (oxy/pid) │ │ cgroupv2 tag │
└─────────────┘ └──────────────┘ └───────┬────────┘
│
v
┌─────────────┐ ┌──────────────┐ ┌────────────────┐
│ Network │<────│ tc filter │<────│ tc HTB qdisc │
│ Interface │ │ (cgroup │ │ (rate limit) │
│ (eth0) │ │ match) │ │ │
└─────────────┘ └──────────────┘ └────────────────┘
Download (ingress)
┌─────────────┐ ┌──────────────┐ ┌────────────────┐
│ Network │────>│ nftables │────>│ tc HTB qdisc │
│ Interface │ │ (prerouting │ │ (rate limit) │
│ (eth0) │ │ mark) │ │ │
└─────────────┘ └──────────────┘ └────────────────┘
# Print version
oxy -v
# Print detailed info
oxy -iExample output of oxy -i:
Version: v2.0.0
Build: linux-x86_64 (ad36a81)
Copyright: (c) 2026 Rezky_nightky
License: MIT
Source: https://github.com/oxyzenq/oxy
# Quick quality checks
./build.sh check-all
# Build release binary
./build.sh release
# Full CI pipeline (checks + release build)
./build.sh ciMIT License — Copyright (c) 2026 Rezky_nightky
See LICENSE for details.
Rezky_nightky — GitHub
