Routing Switch
NETWORK TOOL
Control traffic flow, DNS behavior, and visible network identity.
Each network guide explains practical routing or verification scenarios before pointing to exact generated flags.
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
File Information
| Property | Value |
|---|---|
| Binary Name | routing-switch |
| Version | 9.0.1 |
| Build Date | REDACTED-BUILD-TIME |
| Rust Version | 1.70.0 |
| File Size | 9.5MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Network & Routing |
| Description | System-wide traffic routing through various proxy protocols |
| JSON Data | View Raw JSON |
SHA256 Checksum
Key Features
Multi-Protocol Support
| Protocol Type | Description |
|---|---|
| Traditional VPNs | OpenVPN and WireGuard with native kernel routing |
| Tor Integration | Routes through Tor using redsocks transparent proxy |
| SOCKS5 Proxies | Dante for generic SOCKS5 proxy support |
| Shadowsocks | High-performance encrypted proxy |
| V2Ray | Advanced proxy with multiple transport protocols |
| Xray Variants | VLESS, VLESS-Reality, Trojan, and VMess (legacy) protocols |
| Mieru/Mita | Censorship-resistant proxy protocol |
| Hysteria2 | QUIC-based proxy for unreliable networks |
| Auto-Selection | Intelligently chooses best protocol based on availability |
Why Routing Switch is Essential
| Feature | Description |
|---|---|
| System-Wide Protection | Routes ALL traffic, not just browser |
| Protocol Flexibility | Switch between protocols based on needs |
| Authentication Required | Works with online-auth for secure access |
| Zero Configuration | Protocols are pre-configured from authentication cards |
TL;DR - Essential Commands
Important: Requires authentication via online-auth before use. Use sudo for connection commands.
# Auto-select and connect to best protocol (requires auth)
sudo routing-switch auto-select
# Connect to specific protocol examples
sudo routing-switch connect openvpn
sudo routing-switch connect wireguard
sudo routing-switch connect tor
sudo routing-switch connect dante
sudo routing-switch connect shadowsocks
sudo routing-switch connect v2ray
sudo routing-switch connect xray-vless
sudo routing-switch connect xray-vless-reality
sudo routing-switch connect xray-trojan
sudo routing-switch connect mita
sudo routing-switch connect hysteria2
# Check connection status
routing-switch status
# Disconnect current connection
sudo routing-switch disconnect
# List available protocols
routing-switch list-protocols
Understanding Protocol Support
How Routing Works
Routing Switch requires authentication through online-auth to access server configurations. The routing-switch automatically fetches your "card" containing all server details:
# Step 1: Authenticate first (required)
sudo online-auth authenticate
# Step 2: Connect using routing-switch (automatically fetches card)
sudo routing-switch auto-select
Available Protocols
# List all available protocols with scores
routing-switch list-protocols
# List protocols sorted by speed (fastest first)
routing-switch list-protocols --sort-by-speed
# List protocols sorted by reliability
routing-switch list-protocols --sort-by-security
# Test specific protocol connectivity
routing-switch test-protocol openvpn
routing-switch test-protocol wireguard
# Benchmark all protocols
routing-switch benchmark
Protocol Categories:
| Category | Protocols | Description |
|---|---|---|
| Native Routing | OpenVPN, WireGuard | Direct kernel-level routing (own interfaces: tun0, wg0) |
| Redsocks Proxy | Tor | Transparent SOCKS proxy redirection via iptables NAT |
Tun2socks (shared tun_routing) |
Dante (SOCKS5), Shadowsocks, V2Ray, Xray-VLESS, Xray-VLESS-Reality, Xray-Trojan, Xray-VMess (legacy), Mieru/Mita, Hysteria2 | TUN-interface proxy routing — Dante is the SOCKS5 client and is also the fallback for generic socks-proxy connections (verified at routing-switch/src/protocols/mod.rs:132,142). Xray-VMess is implemented (mod.rs:139) but excluded from PROTOCOL_SECURITY_SCORES; use VLESS/Reality or Trojan for new connections. |
Connection Management
# Connect to best available protocol
sudo routing-switch auto-select
# Connect to specific protocol
sudo routing-switch connect openvpn
sudo routing-switch connect wireguard
sudo routing-switch connect shadowsocks
sudo routing-switch connect v2ray
# Check current status
routing-switch status
# Check DNS and resolver endpoints used by active route
routing-switch dns-info
routing-switch dns-info --json
# Optional: verify no DNS leaks with the dedicated tester
dns-leak test --json
# Disconnect current connection
sudo routing-switch disconnect
# Reset all routing to defaults
sudo routing-switch reset
DNS Information:
The dns-info command shows DNS and resolver endpoint details for the active routing profile. Use it to verify where DNS traffic is being sent after protocol switches.
Microsocks SOCKS5 Server
Turn your Kodachi machine into a SOCKS5 proxy server so other devices on your network can route their traffic through your active routing-switch connection:
# Step 1: Connect routing-switch to any service first
sudo routing-switch connect wireguard
# or any other protocol: v2ray, shadowsocks, hysteria2, etc.
# Step 2: Enable microsocks server (auto port detection)
sudo routing-switch microsocks-enable -u USERNAME -p PASSWORD
# Enable with specific port (30050-30054 range)
sudo routing-switch microsocks-enable -u USERNAME -p PASSWORD --port 30051
# Check server status
routing-switch microsocks-status
routing-switch microsocks-status --json
# Disable microsocks server
sudo routing-switch microsocks-disable
Microsocks Features:
| Feature | Description |
|---|---|
| Port Range | Auto-selects from 30050-30054 or specify manually |
| Authentication | Username and password required |
| Process Management | PID tracking and graceful shutdown |
| Status Monitoring | Real-time status with uptime tracking |
| Network Interfaces | Listens on all interfaces (0.0.0.0) |
Workflow Example:
| Step | Action | Description |
|---|---|---|
| 1 | sudo routing-switch connect wireguard |
Connect to your VPN/proxy service |
| 2 | sudo routing-switch microsocks-enable -u microkodachi -p 'SecurePass123' |
Start SOCKS5 server |
| 3 | Connect other devices | Use socks5://microkodachi:SecurePass123@YOUR_IP:30050 |
Security Notes:
| Practice | Description |
|---|---|
| Strong Credentials | Use complex username and password |
| Network Security | Only enable on trusted networks |
| Connection First | Always connect routing-switch before enabling microsocks |
| Port Management | Microsocks uses dedicated 30050-30054 range |
Configuration Export
# Export all protocol configurations
routing-switch export-config
# Export specific protocol configuration
sudo routing-switch export-config wireguard
sudo routing-switch export-config shadowsocks
sudo routing-switch export-config v2ray
# Show configuration for current protocol
routing-switch showconfig
# Show configuration as URL
routing-switch showconfigurl
# Show configuration as QR code
routing-switch showconfigqr
# Generate QR code files for mobile import
routing-switch showconfigqr shadowsocks
routing-switch showconfigqr v2ray
QR Code Export:
The showconfigqr command exports protocol configurations as QR codes that mobile clients can scan directly:
- Generates protocol-specific QR payloads
- Works with WireGuard, Shadowsocks, V2Ray, and Xray variants
Mobile Device Integration
Connect your mobile devices using QR codes generated by routing-switch. Different protocols work with different mobile apps:
WireGuard (Official App)
Scan with: WireGuard official app (iOS/Android)Shadowsocks, V2Ray, and Xray Protocols
# Generate QR codes for various protocols
routing-switch showconfigqr shadowsocks
routing-switch showconfigqr v2ray
routing-switch showconfigqr xray-trojan
routing-switch showconfigqr xray-vless
Recommended Mobile Apps:
| Protocol | iOS | Android | Notes |
|---|---|---|---|
| WireGuard | WireGuard (official), Happ | WireGuard (official), TunSafe (low-maintenance) | TunSafe website hasn't updated since 2020 |
| OpenVPN | OpenVPN Connect | OpenVPN Connect, OpenVPN for Android (open-source) | |
| Shadowsocks | Shadowrocket ($2.99), Outline, RocketTunnel (free), Streisand, Happ | V2RayNG (GitHub-only), Outline, RocketTunnel (free) | V2RayNG removed from Google Play 2025-04-30; RocketTunnel supports Shadowsocks-2022 |
| V2Ray (VMess/WS) | Shadowrocket, Streisand, Stash ($5.99), Happ | V2RayNG (GitHub-only), Hiddify | |
| Xray VLESS/Reality/Trojan/VMess | Shadowrocket, V2Box, Streisand, Hiddify, Happ | V2RayNG (GitHub-only), Hiddify, NekoBox (GitHub/F-Droid) | NekoBox NOT on Play Store |
| Hysteria2 | Hiddify, Streisand, Happ | Hiddify, NekoBox (GitHub/F-Droid) | |
| Mita (Mieru) | — (no iOS client) | NekoBox + mieru plugin | Android-only via plugin |
| Dante (SOCKS5) | Shadowrocket (SOCKS5 mode) | System SOCKS proxy settings | Generic SOCKS5 — most apps with a SOCKS field work |
| Tor SOCKS | Onion Browser | Orbot | |
| Private DNS | iOS Settings > DNS, DNSCloak | Android Settings > Private DNS, Intra |
Bonus: FairVPN (iOS + Android) is a free client that supports VLESS, VMess, Trojan, Shadowsocks, and SSR. Note it is geo-blocked in CN, RU, SA, IN, and CA — outside those regions it is a solid additional option.
How to Connect:
| Step | Action |
|---|---|
| 1 | Generate the QR code for your desired protocol |
| 2 | Open your chosen mobile app |
| 3 | Scan the QR code using the app's import feature |
| 4 | The app will automatically configure the connection |
| 5 | Enable the VPN/proxy in the app to connect |
Dashboard: Mobile manager tab
The Mobile manager tab gives logged-in users a fast GUI path to push any configured VPN or proxy connection to a phone without touching the CLI.
Where to find it:
- Lite sidebar — Smartphone icon, after the VPN Providers entry
- Advanced sidebar — Smartphone icon under the Advanced section
- Welcome screen — Mobile tab, after the Advanced tab
Sign-in required. The page is locked until the user authenticates with their Kodachi account.
Per-protocol row actions — each active protocol row exposes four buttons:
| Action | What it does |
|---|---|
| Copy share link | Copies the share URI (e.g. vmess://…, wg://…) to the clipboard |
| QR | Shows a scannable QR code for that protocol in a modal |
| Export | Writes the config file to disk (e.g. .conf, .json, .ovpn) |
| Config | Displays the raw config text inline for manual copy |
A tooltip on each row surfaces the recommended mobile app(s) for that protocol, matching the table above.
Bulk actions (top of the tab):
- All QR codes — opens a gallery modal showing QR codes for every active protocol at once
- Export all configs — writes all config files to a single download folder
- Save all QRs — saves every QR code as a PNG to disk
- Copy all share links — copies all share URIs to the clipboard in one action
External provider exports — a dedicated section lets you bulk-export configs for Riseup and VPNGate profiles in the same four formats, so you can carry a third-party connection to your phone with the same one-click flow.
Full authentication card viewer — at the bottom of the tab the raw card JSON for the currently loaded authentication card is shown, useful for manual imports or debugging connection parameters.
External VPN Providers (catalog-driven third-party VPNs)
The providers subcommand exposes a curated catalog of 13 third-party VPN providers (free anonymous pools, paid commercial accounts, and your own pasted configs) through one CLI surface plus a dedicated dashboard tab. The catalog file at /opt/kodachi/dashboard/hooks/config/vpn-providers-public-api.json is user-editable.
Catalog tiers:
| Tier | Providers | What it means |
|---|---|---|
| Anonymous, free | VPN Gate, Riseup | No account required — direct connect |
| Paid commercial | NordVPN, IVPN, PIA, Surfshark, AirVPN, Mullvad (WireGuard-only since 2026), Windscribe | Public auto-fetch endpoint + per-user credentials stored at ~/.config/kodachi/vpn-credentials.json (mode 0600) |
| Manual download only | ProtonVPN, ExpressVPN, TorGuard | No public auto-fetch API — paste their .ovpn via Import config |
| Custom (paste your own) | custom pseudo-provider |
Auto-detects OpenVPN, WireGuard, Shadowsocks, V2Ray, Hysteria2, plus vmess://, vless://, trojan://, ss://, hysteria2://, tuic:// URI schemes, plus Clash YAML and sing-box JSON multi-profile subscriptions |
Discovery and browsing:
# List every provider with cache freshness
routing-switch providers list
# Fetch the live profile list (one provider)
sudo routing-switch providers fetch vpngate --force
# Browse cached profiles with country / protocol filters
routing-switch providers list-profiles vpngate --country jp --limit 5
routing-switch providers list-profiles riseup --json-pretty
Connecting (auto-injects saved credentials when needed):
# Save credentials for a paid provider (one-time)
sudo routing-switch providers credentials-set nordvpn \
--field username=foo --field password=bar
# Connect via a specific profile
sudo routing-switch providers connect nordvpn pl150-nordvpn-com_udp --force
# Or let routing-switch pick the best server
sudo routing-switch providers connect-fastest vpngate --country jp --force
sudo routing-switch providers connect-random vpngate --country jp --force
Manual latency probe (opt-in, never auto-runs):
# Ping each cached server (ICMP → TCP-connect fallback), store latency_ms
routing-switch providers benchmark vpngate --country jp --top 20 --concurrency 8 --timeout 3
# After a benchmark, connect-fastest prefers measured latency over
# provider-reported speed_bps.
Bringing your own config:
# Paste/import any OpenVPN .ovpn, WireGuard .conf, Shadowsocks/V2Ray JSON,
# Hysteria2 YAML, or any of the supported URI schemes
routing-switch providers import-config --name "My VPN" --file ~/Downloads/my.ovpn
# Dry-run preview (CV-3 draft-validate) before committing
routing-switch providers validate-config --text "vless://uuid@example.com:8443?type=tcp#NY"
# Multi-profile subscription import (Clash YAML or sing-box JSON):
routing-switch providers import-config --name "Clash sub" --file ~/Downloads/clash.yml
Country / IP resolution helpers:
# Look up a profile's country via ip-fetch (auto for Riseup gaps)
routing-switch providers resolve-country riseup vpn12-nyc_udp_1194
# Bulk DNS-resolve hostnames in a provider's cache
routing-switch providers resolve-ips riseup --concurrency 8
# Force re-verify a country (Verify mode)
routing-switch providers resolve-country vpngate <profile_id> --force
Dashboard equivalent: every CLI above has a 1-click GUI in the "External VPN Providers" tab (Globe icon on Lite/Full/Circle sidebars). The tab has:
- Filter bar (search, free/paid, anonymous-only, protocol, manual-only toggle)
- Per-provider detail view with sortable columns (flag, name, remote, protocol, port, load, speed, latency)
- Action chips: Fastest (lightning), Random (shuffle), Resolve IPs (globe), Resolve countries (flag), Test latency (timer)
- Connected-state banner with Disconnect button when a routing-switch VPN is active
- Favorite stars persisted to localStorage; favorites float to the top of any sort
- Credentials editor that reads catalog metadata (labels, placeholders, hint URLs, regex validation)
- Import config widget with Validate (dry-run preview) + Import buttons and protocol-hint dropdown
(?)help icon opens an in-panel drawer with the full reference
Recovery and Cleanup
# Clean up orphaned processes
sudo routing-switch cleanup
# Recover from partial failure
sudo routing-switch recover
# Reset all routing tables
sudo routing-switch reset
Network Prerequisites
Check and manage network prerequisites for VPN connections:
# Recover networking state and dependencies after failures
sudo routing-switch recover
# Clean orphaned processes and stale routes
sudo routing-switch cleanup
# Verify resulting state in JSON format
routing-switch status --json
Use recover first when routing setup fails, then cleanup to remove stale resources before reconnecting.
For advanced users who need access to all available commands and options, please refer to the auto-generated command reference which includes:
| Feature | Description |
|---|---|
| Protocol Testing | Protocol testing and benchmarking |
| Configuration Management | Configuration export and import |
| Mobile Integration | QR code generation for mobile |
| Custom Config | Custom configuration files |
| Recovery Tools | Recovery and cleanup operations |
| CLI Reference | All command-line flags and parameters |
Security Notes
Important Security Practices:
| Practice | Description |
|---|---|
| Authentication | Always authenticate with online-auth first |
| Verification | Verify connection status after connecting |
| DNS Security | Test for DNS leaks after connection |
| Auto-Selection | Use auto-select for optimal security |
| Proper Disconnection | Disconnect properly to restore routing |
| Monitoring | Monitor connection status regularly |
Performance
| Metric | Value | Description |
|---|---|---|
| Connection Time | 2-10 seconds | Depending on protocol |
| Memory Usage (VPN) | ~40MB | For VPN protocols |
| Memory Usage (Proxy) | ~60MB | For proxy protocols |
| CPU Usage (VPN) | < 10% | For VPN protocols |
| CPU Usage (Proxy) | < 15% | For proxy protocols |
| WireGuard Speed | 90-95% | Of line speed |
| OpenVPN Speed | 70-80% | Of line speed |
| Tor Speed | 1-10 Mbps | Typical speeds |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: Auto-Select Best Protocol with Authentication
Use auto-select to connect to the best available protocol after authentication.
# Step 1: Authenticate first
sudo online-auth authenticate
# Step 2: Auto-select best protocol
sudo routing-switch auto-select
# Expected: Selected WireGuard (best overall score)
# Step 3: Verify connection status
sudo routing-switch status
# Expected: Protocol: wireguard, Status: Connected
# Step 4: Check IP changed
ip-fetch
# Expected: VPN IP address displayed
# Step 5: Verify no DNS leaks
dns-leak test
Cross-binary workflow: online-auth + routing-switch + ip-fetch + dns-leak
When to run: First time setup or when you need the fastest/most secure protocol available.
Scenario 2: Double-Layer Setup (WireGuard + Tor Stacking)
Create a layered connection with WireGuard and Tor for maximum anonymity.
# Step 1: Connect to WireGuard
sudo routing-switch connect wireguard
# Step 2: Verify WireGuard connection
sudo routing-switch status
# Expected: Protocol: wireguard, Status: Connected
# Step 3: Layer Tor on top using --force
sudo routing-switch connect tor --force
# Expected: Traffic flows through BOTH protocols (double encryption)
# Step 4: Check Tor is active
ip-fetch check-tor
# Expected: Tor IP address confirmed
# Step 5: Verify routing
sudo routing-switch status
# Expected: Shows Tor routing with WireGuard still active
# Step 6: Test connectivity
sudo health-control net-check
Cross-binary workflow: routing-switch + tor-switch + ip-fetch
When to run: Maximum anonymity scenarios requiring double VPN protection. Automate this with workflow-manager.
Scenario 3: Corporate VPN with LAN Access and Failover
Connect to corporate VPN while maintaining LAN access and automatic failover.
# Step 1: Authenticate
sudo online-auth authenticate
# Step 2: Connect with metric routing + hybrid DNS + exclude private networks
sudo routing-switch connect wireguard --metric --dns-mode hybrid --exclude-private
# Expected: Using metric routing with local network access
# Step 3: Verify LAN access preserved
ping 192.168.1.1
# Expected: Local router responds
# Step 4: Check failover capability
sudo routing-switch status
# Expected: Metric routing mode active
# Step 5: Test VPN connection
sudo health-control net-check
# Step 6: Monitor connection
routing-switch status --json
Cross-binary workflow: online-auth + routing-switch + health-control
When to run: Corporate environments requiring VPN with LAN access and automatic failover if VPN drops.
Scenario 4: Censorship Resistance — Multi-Protocol Testing
Test multiple protocols to find which works in censored networks.
# Step 1: Authenticate
sudo online-auth authenticate
# Step 2: Test all available protocols
routing-switch test-protocol all
# Expected: Testing: Tor [OK], Shadowsocks [OK], V2Ray [FAIL]...
# Step 3: Benchmark working protocols
routing-switch benchmark --iterations 5
# Expected: Performance metrics for each protocol
# Step 4: List protocols sorted by reliability
routing-switch list-protocols --sort-by-security
# Step 5: Connect to most reliable censorship-resistant protocol
sudo routing-switch connect xray-vless-reality
# Expected: Successfully connected to Xray VLESS Reality server
# Step 6: Verify connection works
ip-fetch
Cross-binary workflow: online-auth + routing-switch + ip-fetch
When to run: In censored regions to find working protocols. Automate this with workflow-manager.
Scenario 5: Mobile SOCKS5 Proxy Server (Microsocks)
Turn Kodachi into a SOCKS5 proxy server for mobile devices.
# Step 1: Connect to any routing protocol
sudo routing-switch connect wireguard
# Step 2: Enable microsocks server with credentials
sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds'
# Expected: Microsocks server started on port 30050
# Step 3: Check server status
sudo routing-switch microsocks-status
# Expected: Status: Running, Port: 30050, PID: 12345
# Step 4: Get connection details
sudo routing-switch microsocks-status --json
# Expected: {"status":"running","port":30050,"pid":12345}
# Step 5: Connect mobile device using socks5://microkodachi-8273:S@Cur9P@s@Wo-Ds@YOUR_IP:30050
# Step 6: Stop server when done
sudo routing-switch microsocks-disable
Cross-binary workflow: routing-switch + health-control + logs-hook
When to run: When sharing VPN connection with mobile devices on your network.
Scenario 6: QR Code Generation for Mobile Config Import
Generate QR codes for easy mobile device configuration.
```bash
Step 1: Authenticate
sudo online-auth authenticate