meow-rs

A high-performance Rust implementation of the mihomo (Clash Meta) proxy kernel. Rule-based tunneling with support for multiple proxy protocols, transparent proxy, DNS snooping, a REST API, and a built-in web dashboard.

Features

Proxy Protocols

• Shadowsocks -- TCP and UDP relay, AEAD and stream ciphers (aes-256-gcm, chacha20-ietf-poly1305, etc.)
• Trojan -- TLS 1.2/1.3 (BoringSSL), SNI, optional skip-cert-verify
• Hysteria2 -- QUIC-based TCP and UDP relay, Salamander obfs, port hopping, down bandwidth auth hint, SNI, skip-cert-verify, and certificate pinning
• VLESS -- Plain VLESS and XTLS-Vision splice; TLS, WebSocket, gRPC, H2, HTTPUpgrade transports
• VMess -- AEAD VMess outbound with TCP/WebSocket transports
• HTTP -- HTTP CONNECT outbound proxy with optional TLS and basic auth
• SOCKS5 -- SOCKS5 outbound proxy with optional TLS and auth
• Snell -- v3/v4/v5 TCP, UDP-over-TCP, optional HTTP/TLS obfs; v4/v5 connection reuse
• AnyTLS -- AnyTLS outbound (anytls feature; in the full bundle, so the release binaries include it)
• Direct -- Direct connection to destination
• Reject -- Drop connections (with configurable behavior)

TLS & Privacy

• ECH (Encrypted Client Hello) -- DNS-based ECH config fetching from HTTPS/SVCB records; BoringSSL backend (boring-tls feature)
• uTLS Fingerprinting -- Chrome, Firefox, Safari, iOS, Android, Edge profiles to bypass TLS fingerprint detection
• BoringSSL is the single crypto library for the whole app. Every proxy handshake, health check, DoT/DoH upstream, internal HTTP(S) fetch (uTLS fingerprints and ECH included), and the Hysteria2 QUIC transport link one vendored BoringSSL. rustls is not used at runtime at all

Proxy Groups

• Selector -- Manual proxy selection via REST API or web UI
• URLTest -- Automatic selection based on latency with tolerance threshold
• Fallback -- Automatic failover to first alive proxy
• LoadBalance -- Round-robin or consistent-hashing distribution
• Relay -- Chained proxy tunneling through multiple hops

Rule Engine

Logic composition rules (AND, OR, NOT) are also supported for combining conditions.

DNS

• UDP DNS server with configurable listen address
• Main + fallback nameserver groups
• Response caching and in-flight request deduplication
• DNS snooping -- reverse IP→domain lookup table for transparent proxy hostname recovery

Inbound Listeners

• Mixed -- Auto-detects HTTP or SOCKS5 on a single port
• HTTP Proxy -- HTTP CONNECT and plain HTTP forwarding
• SOCKS5 -- SOCKS5 with optional authentication
• Transparent Proxy (TProxy) -- Kernel-level traffic interception via nftables (Linux) or pf (macOS)
• TUN / Wintun -- L3 inbound (tun:). On Windows this is a Wintun adapter and is the transparent-proxy path; official Windows zips ship wintun.dll beside meow.exe, and the binary also embeds a copy to extract if the sidecar is missing

Transparent Proxy

Intercept local traffic without per-app proxy configuration.

• Windows: Wintun TUN adapter (tun:). Requires an elevated process and wintun.dll next to meow.exe (included in official zips). Fake-IP DNS capture; see docs/tun.md.
• Linux / macOS: nftables redirect (Linux) or pf anchor (macOS) via tproxy-port
• Loop avoidance (tproxy): SO_MARK on outbound DIRECT sockets (Linux), UID-based bypass (macOS), plus IP bypass for upstream proxy servers
• SNI extraction: Peek at TLS ClientHello to recover hostname for HTTPS traffic
• DNS snooping: Reverse IP→domain lookup from recent DNS queries for non-TLS traffic
• RAII firewall guard: tproxy rules automatically cleaned up on shutdown (SIGINT/SIGTERM)
• Configurable via tun:, tproxy-port, routing-mark, and tproxy-sni in YAML

The built-in firewall transparently proxies the host's own traffic. To build a LAN gateway that forwards and proxies other devices' traffic, see docs/tproxy-gateway.md.

Web Dashboard

Built-in web UI served at http://<api-addr>/ui with:

• Overview -- Mode selector, listening ports, live traffic stats
• Proxies -- Click-to-switch selector groups, view all proxy group members
• Subscriptions -- Add/refresh/delete Clash YAML subscription URLs (auto-cached to disk)
• Proxy Groups -- Create/edit/delete selector, url-test, fallback groups
• Rules -- Add/delete/reorder rules with drag-and-drop, search/filter

Subscription Management

• Fetch and import Clash YAML subscriptions (proxies, groups, rules)
• Auto-save to disk -- cached data loads on restart without re-fetching
• Background refresh on configurable intervals
• Multi-pass group resolution for inter-group references

REST API

Tunnel

• Three routing modes: Rule, Global, Direct
• Bidirectional TCP relay and UDP NAT session tracking
• Per-connection traffic statistics with connection lifecycle management

Benchmarks

Side-by-side against upstream Go mihomo v1.19.29 on the same host (Apple M4 arm64, macOS 26.5.2, loopback 127.0.0.1). Both binaries use identical config: mode: direct, SOCKS5 listener on port 17890, DNS disabled. Reproduce with bash bench.sh (auto-downloads the latest Go mihomo release).

Per-metric medians of three bash bench.sh runs; numbers will vary with host load. Loopback bulk-transfer throughput measures per-proxy CPU overhead, not real-network throughput — both kernels saturate multi-Gbps links with headroom. For the full methodology, three-run-median protocol, and workload definitions (W1–W5), see ADR-0006 and docs/benchmarks/index.md.

Architecture

flowchart TD
    inbound["Inbound listeners<br/>Mixed / HTTP / SOCKS5 / TProxy"] --> tunnel["Tunnel<br/>routing, relay, connection stats"]
    api["REST API + Web UI<br/>Axum"] --> tunnel
    api --> runtime["Runtime state<br/>config, subscriptions, proxy groups, rules"]
    runtime --> tunnel
    tunnel <--> dns["DNS resolver<br/>cache, fake-IP, policy, snooping"]
    tunnel --> rules["Rule engine<br/>linear / indexed / IR matchers"]
    rules --> outbounds["Proxy adapters and groups<br/>SS, Trojan, VLESS, VMess, Snell, Hysteria2, Direct, Reject"]
    outbounds --> remote["Remote server / DIRECT"]

11 workspace crates with clear separation of concerns:

Quick Start

Build

Requires Rust 1.89+ (the workspace pins rust-version = "1.89" and CI enforces it via a dedicated MSRV job). rust-toolchain.toml additionally pins the default channel rustup uses in the checkout, so CI and local builds share one toolchain.

cargo build --release

Run

# Copy the example config and edit it
cp config.example.yaml config.yaml
# Edit config.yaml with your proxy servers...

# Run
./target/release/meow -f config.yaml

# Test config validity
./target/release/meow -f config.yaml -t

Install as system service

Linux (systemd):

sudo ./target/release/meow install -f /path/to/config.yaml

# Manage the service
sudo systemctl status meow
sudo systemctl restart meow
sudo journalctl -u meow -f

# Uninstall
sudo ./target/release/meow uninstall

Windows (Service Control Manager):

Open PowerShell as Administrator, then run:

# Install, enable automatic startup, and start the service
.\target\release\meow.exe install -f 'C:\path\to\config.yaml'

# Optional: pin the meow resource/cache home explicitly. The global -d flag
# must appear before the install subcommand.
.\target\release\meow.exe -d 'D:\meow-data' install -f 'C:\path\to\config.yaml'

# Check status
.\target\release\meow.exe status
Get-Service meow

# Manage the service
Stop-Service meow
Start-Service meow
Restart-Service meow

# List the daily rolling logs (the seven newest files are retained)
Get-ChildItem "$env:ProgramData\meow\logs\meow.*.log"

# Follow the newest log
$log = Get-ChildItem "$env:ProgramData\meow\logs\meow.*.log" |
  Sort-Object LastWriteTime | Select-Object -Last 1
Get-Content $log.FullName -Wait

# Uninstall
.\target\release\meow.exe uninstall

Installation keeps using the configuration file at the path passed to -f, starts the service immediately, and configures it to start automatically with Windows. A relative -f follows the same rule as a direct run: it is resolved under -d when a home directory is given, otherwise under the current directory. Running install again updates the registered binary/configuration and restarts the service. When -d is omitted, the installer resolves and records the same default meow home used by a normal CLI launch (for example, E:\test\meow when launched from E:\test); the selected path is printed as Home after installation. The service runs as LocalSystem, so that account must have read/write access to the configuration path and the selected Home. After upgrading from an older service build, run install again to refresh the SCM launch arguments. Uninstalling preserves both the configuration and the logs.

Security notes:

• The service executes the binary at its install-time location as LocalSystem on every boot. Copy meow.exe to a directory writable only by administrators (for example, C:\Program Files\meow) and run install from there, rather than registering a binary inside a user-writable directory.
• %ProgramData%\meow\logs inherits the default ProgramData ACLs, so log files (which include destination hosts of proxied connections) are readable by all local users. Tighten the ACL on %ProgramData%\meow if that matters on a shared machine.

macOS (launchd user agent):

./target/release/meow install -f /path/to/config.yaml

# Config is copied to ~/Library/Application Support/meow/config.yaml
# Logs are written to ~/Library/Logs/meow/

# Check status
./target/release/meow status

# View logs
tail -f ~/Library/Logs/meow/meow.log

# Uninstall
./target/release/meow uninstall

OpenWrt (opkg + LuCI):

Official .ipk packages for aarch64 routers — including a luci-app-meow that embeds the built-in web panel in LuCI — are attached to every release. See docs/openwrt.md.

Open the Web UI

After starting, open your browser to:

http://127.0.0.1:9090/ui

From the Subscriptions tab you can add a Clash subscription URL to import proxies, groups, and rules automatically.

Use the Proxy

# HTTP proxy
curl --proxy http://127.0.0.1:7890 https://ipinfo.io

# SOCKS5 proxy
curl --proxy socks5://127.0.0.1:7890 https://ipinfo.io

# Set as system proxy (macOS)
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

Example Configuration

mixed-port: 7890
mode: rule
log-level: info

# Transparent proxy (requires root/sudo)
# tproxy-port: 7893
# tproxy-sni: true
# routing-mark: 9527

external-controller: 127.0.0.1:9090

dns:
  enable: true
  listen: 127.0.0.1:1053
  nameserver:
    - 8.8.8.8
  fallback:
    - 8.8.4.4

proxies:
  - name: my-ss
    type: ss
    server: 1.2.3.4
    port: 8388
    cipher: aes-256-gcm
    password: "secret"
    udp: true

  - name: my-trojan
    type: trojan
    server: 5.6.7.8
    port: 443
    password: "secret"
    sni: example.com
    skip-cert-verify: false

  - name: my-snell
    type: snell
    server: ss.example.com
    port: 8443
    psk: "your-psk"
    version: 3
    udp: true
    obfs-opts:
      mode: http
      host: /

  - name: my-hy2
    type: hysteria2
    server: hy2.example.com
    port: 443
    ports: "443,8443-8445"
    hop-interval: 30
    password: "secret"
    sni: hy2.example.com
    skip-cert-verify: false
    udp: true
    up: "100 Mbps"
    down: "100 Mbps"
    obfs: salamander
    obfs-password: "obfs-secret"

proxy-groups:
  - name: Proxy
    type: select
    proxies: [my-ss, my-trojan, my-snell, my-hy2]

  - name: Auto
    type: url-test
    proxies: [my-ss, my-trojan, my-snell, my-hy2]
    url: http://www.gstatic.com/generate_204
    interval: 300

rules:
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - DOMAIN-SUFFIX,google.com,Proxy
  - MATCH,Proxy

See config.example.yaml for a full annotated example.

Testing

Dashboard tests run the shipped HTML in Chromium against an isolated simulated controller, covering navigation, editing, authentication, error handling, and live traffic. They do not access a running meow instance or real subscriptions. The same suite runs in the dashboard CI job; failures retain Playwright traces.

cd tests/dashboard
npm ci
npx playwright install chromium
npm test

The dependency-free traffic lifecycle regression tests can also run separately:

node --test crates/meow-api/tests/ui_test.cjs

# All unit tests
cargo test --lib

# Rules tests (78 tests covering all rule types)
cargo test --test rules_test

# API and config persistence tests (54 tests)
cargo test --test api_test
cargo test --test config_persistence_test

# Trojan integration tests (embedded mock server, no external deps)
cargo test --test trojan_integration

# Hysteria2 Docker integration tests (requires Docker)
MEOW_REQUIRE_DOCKER=1 cargo test -p meow-proxy --features hysteria2 --test hysteria2_integration -- --nocapture

# Shadowsocks integration tests (requires ssserver)
cargo install shadowsocks-rust --features "stream-cipher aead-cipher-2022" --locked
cargo test --test shadowsocks_integration

# Transparent proxy end-to-end tests (requires Docker)
bash tests/test_tproxy_qemu.sh

Contributing

See CONTRIBUTING.md. In short: meow-rs is a client-only kernel (no server-side features), new features and config keys should follow mihomo mainline, and every PR must pass the full CI test bar and respect the ADRs in docs/adr/.

License

MIT — Copyright (c) 2026 Max Lv. See LICENSE.