A high-performance VPN/proxy tool that routes system traffic through VLESS proxy nodes.
This tool automates the process of fetching VLESS subscriptions, configuring Xray or Sing-box, and managing necessary routing bypasses to ensure a stable, loop-free connection.
animabox uses Xray's native tun inbound for system-wide proxying by default, or local proxy mode backed by Xray or Sing-box.
- Native TUN Engine: Direct system traffic handling for maximum performance.
- Proxy Mode: Local SOCKS5+HTTP proxy for selective application routing (no sudo required).
- Alternative Core: Xray-core is the default core; Sing-box remains available via
-core sing-box. - Auto Port-Jump: In proxy mode, automatically finds a free port if the requested one is busy.
- Concurrent Latency Selection: Simultaneously pings all available nodes from your subscription/file and selects the one with the lowest latency instantly.
- Local & Remote Support: Works with both subscription URLs and local JSON configuration files.
- Protocol Filtering: Optional VLESS-only filtering (enabled by default) to ensure compatibility.
- Auto-Routing: Automatically detects the default gateway and routes transport traffic through the physical interface, preventing routing loops (TUN mode).
- Stability: Integrated keepalives and MTU optimization to ensure persistent, reset-free connections.
- Self-Contained: Manages its own routing table and DNS hijacking (via DoH over VLESS) to eliminate dependency on OS-level DNS setups.
- Xray-core is auto-fetched from
vadash/Xray-corewhen-core xrayis used (falls back toxrayinPATH). - Hiddify sing-box binary is auto-fetched on first run (falls back to
sing-boxinPATH) when-core sing-boxis used. - TUN mode must be run with
sudoto manage network interfaces and routing tables. - Proxy mode does NOT require
sudo. - Xray geodata can be refreshed with
scripts/update_xray_dat.sh; it updates/usr/share/xrayby default.
go build -o animabox cmd/animabox/main.gochmod +x run_vpn.sh
# TUN mode (system-wide VPN, requires sudo)
sudo ./run_vpn.sh "YOUR_SUBSCRIPTION_URL"
sudo ./run_vpn.sh "config.json"
# Proxy mode (local proxy, no sudo)
./run_vpn.sh "YOUR_SUBSCRIPTION_URL" proxy
./run_vpn.sh "YOUR_SUBSCRIPTION_URL" proxy 8080
./run_vpn.sh "YOUR_SUBSCRIPTION_URL" proxy 8080 sing-box# Xray TUN mode (default core)
sudo ./animabox -sub "config.json" -mode tun -v
# Xray proxy mode (default core)
./animabox -sub "config.json" -mode proxy -port 1080 -v
# Sing-box TUN mode
sudo ./animabox -sub "config.json" -mode tun -core sing-box -v
# Sing-box proxy mode
./animabox -sub "config.json" -mode proxy -core sing-box -port 1080 -vPress Ctrl+C. The tool will automatically clean up the routing table and restore network state (TUN mode) or simply stop the proxy (proxy mode).
System-wide VPN that captures all traffic through a virtual tun0 interface. Requires sudo. All applications are proxied automatically with no per-app configuration needed.
Xray (default): Uses tun inbound with system routing table management.
Sing-box: Uses tun inbound with gVisor stack.
Local SOCKS5+HTTP proxy on 127.0.0.1:1080 (configurable with -port and -listen). Does NOT require sudo. Only applications explicitly configured to use the proxy will be routed through the VLESS node.
Xray (default): Uses mixed inbound with vadash's leastLoad balancer for multi-node load balancing.
Sing-box: Uses mixed inbound with urltest balancer.
Auto Port-Jump: If the requested port is already in use, the tool automatically increments until a free port is found and prints the actual port to stdout.
- curl:
curl --proxy socks5h://127.0.0.1:1080 https://example.com - wget:
wget -e use_proxy=yes -e https_proxy=127.0.0.1:1080 https://example.com - SSH:
ssh -o ProxyCommand="nc -X 5 -x 127.0.0.1:1080 %h %p" user@host - Environment variables:
export ALL_PROXY=socks5h://127.0.0.1:1080 - Browser: Configure SOCKS5 proxy in browser settings (127.0.0.1:1080)
| Flag | Default | Description |
|---|---|---|
-sub |
(required) | Subscription URL or local JSON file path |
-mode |
tun |
Operating mode: tun or proxy |
-core |
xray |
Core backend: xray or sing-box |
-port |
1080 |
Proxy listen port (proxy mode only) |
-listen |
127.0.0.1 |
Proxy listen address (proxy mode only) |
-vless-only |
true |
Filter to VLESS nodes only |
-v |
false |
Verbose output (show core logs) |
| Protocol | Xray | Sing-box |
|---|---|---|
| VLESS | ✅ | ✅ |
| VLESS + WebSocket | ✅ | ✅ |
| VLESS + gRPC | ✅ | ✅ |
| VLESS + HTTP/2 | ✅ | ✅ |
| VLESS + XHTTP | ✅ (vadash build) | ❌ |
| VLESS + TLS / Reality | ✅ | ✅ |
- Xray (multi-node): Uses vadash's
leastLoadbalancer with per-region fallback (e.g., US primary → JP fallback). Balancer strategy configured via routing rules. - Sing-box (multi-node): Uses urltest latency-based balancer.
Download latest geoip.dat and geosite.dat:
sudo ./scripts/update_xray_dat.sh
# Or with custom config path:
sudo ./scripts/update_xray_dat.sh --config /path/to/config.jsonFiles are installed to /usr/share/xray by default (can be overridden with XRAY_LOCATION_ASSET).
Arch Linux PKGBUILD for vadash's Xray build:
packaging/xray-core-vadash-git/PKGBUILD
cmd/animabox/ — CLI entry point (main.go)
pkg/proxy/ — Config generation (TUN + proxy modes) for both cores
├── singbox.go — Sing-box config generation & runner
├── xray.go — Xray config generation (new)
└── singbox_test.go — Tests for both cores
pkg/subscription/ — VLESS link parsing, subscription fetching, node selection/ping
pkg/singbox/ — Auto-fetch Hiddify sing-box binary from GitHub releases
pkg/xray/ — Auto-fetch Xray binary from vadash/Xray-core releases
data/ — Runtime data (logs, AppSettings.db)
scripts/ — Utility scripts (update_xray_dat.sh)
packaging/ — Distribution packaging (Arch PKGBUILD)
run_vpn.sh — Convenience wrapper (TUN with sudo / proxy without sudo)
MIT