⚠️ Project Status: PAUSEDThis project is currently paused. Core features (monitor, list, profile, watch, QoS, auto-throttle) are functional, but per-process bandwidth limiting via
oxy strictis not fully stable due to a cgroup v2 + nftables integration issue.Known issue:
nftables socket cgroupv2 level N == <inode>expression fails withcgroupv2 path fails: No such file or directoryat runtime. Thelevelkeyword is required by nftables syntax, but the cgroup inode resolution does not match what the kernel expects for the path lookup. This needs deeper investigation into cgroup v2 hierarchy delegation and inode-to-path mapping.Future plans when resuming:
- Investigate cgroup v2 inode resolution vs nftables path lookup mismatch
- Consider systemd slice integration instead of manual cgroup path management
- Evaluate alternative packet classification methods (e.g.,
meta cgroupwithcgroup2mount awareness)- Test on kernel 6.1+ where cgroup v2 socket matching has improved support
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