eycorsican/leaf: a Rust proxy framework where the CLI is only one of the outputs

What leaf solves that a standalone proxy client does not

Most proxy tools are applications: you install them, point them at a config file, and they open a local port. Leaf is structured differently. The Cargo workspace lists four members: leaf, leaf-cli, leaf-ffi and leaf-plugins/shadowsocks, with leaf-cli as the default member. That layout says the protocol engine lives in leaf, the command line tool is a thin consumer of it, and leaf-ffi exposes the same engine across a C ABI so other languages and platforms can call it.

The audience follows from that split. If you are writing a client for a platform where spawning a separate proxy process is awkward (a mobile app, a desktop GUI, a router firmware image), the interesting artifact is the library, not the binary. The README also lists TUN inbound support on Linux, macOS, Windows, iOS and Android, with lwip and smoltcp named as the user-space network stacks. A library that carries its own TCP/IP stack and can capture traffic without a system-wide proxy setting is the shape mobile proxy clients need.

If you only want a proxy to browse through, the framework angle is overhead. The README has no configuration example, no sample config file and no documented flag beyond the build command.

Protocols, transports and the inbound/outbound asymmetry

The README splits capability into three tables, and the split is the most useful thing in it. Proxy protocols cover HTTP (inbound only), SOCKS5, Shadowsocks and Trojan (both directions), and VMess and Vless (outbound only). Transports and security cover WebSocket, TLS, QUIC, AMux, Obfs, Reality and MPTP. Traffic control covers chain (both directions) and failover (outbound only, with a health check).

Read the columns rather than the checkmarks. Leaf is built to be a client: it dials out through VMess, Vless, Reality and Obfs, and it accepts HTTP, SOCKS5, Shadowsocks and Trojan from local applications. A server-side deployment that terminates VMess or Vless is not what these tables describe. Two entries are Leaf-specific rather than borrowed from the Xray or Shadowsocks ecosystem: AMux, described as Leaf specific multiplexing, and MPTP, the Multi-path Transport Protocol for aggregation, which has its own architecture and usage documents under docs/.

Transparent proxying is the other axis. TUN is inbound-only and multi-platform. NF is inbound-only and Windows-specific, built on NetFilter SDK. TPROXY is listed with no inbound or outbound support and the note that it is coming soon, so on Linux the TUN path is the one that exists today.

Building leaf-cli and running it for the first time

The README gives one build command and one invocation. The Makefile wraps the same command as make cli, and it exports CFG_COMMIT_HASH and CFG_COMMIT_DATE from git before building, so the binary can report which commit it came from. Build from the repository root:

cargo build -p leaf-cli --release
./target/debug/leaf --help

The README prints the second line with the debug path even though the first line builds in release mode; the release binary lands under target/release/leaf. Running --help is the only documented way to discover what the CLI accepts, because the README does not list flags or a config format. A development build without the release profile is make cli-dev, which runs cargo build -p leaf-cli with the dev profile from Cargo.toml: opt-level 0 and debug symbols on. The release profile sets opt-level 3, lto true, panic abort and strip symbols, which is a size-and-speed profile for shipping rather than debugging.

The workspace has a test target too:

make test

That runs cargo test -p leaf with --nocapture, so it exercises the library crate rather than the CLI. There is no documented test for leaf-ffi or for the Shadowsocks plugin crate.

Where leaf is the wrong tool

The README documents no configuration file, no environment variables and no CLI flags beyond --help. For a proxy tool that is a real gap: a reader who wants to start a SOCKS5 listener with a Shadowsocks outbound has no documented way to express that. The repository has a docs/ directory, and the README links two files in it (mptp_architecture.md and mptp_usage.md), but nothing in the README describes a general configuration reference.

The second limitation is directional. If your goal is to run a server that accepts VMess or Vless connections, the tables mark both as outbound only, and HTTP as inbound only with no outbound. Reality and Obfs are outbound only as well. A deployment that needs to terminate those protocols on the receiving side is outside what the README claims.

The third is platform coverage for transparent proxying. TPROXY, the Linux mechanism many router and gateway setups rely on, is listed as coming soon with no inbound or outbound support. The alternative on Linux is TUN, which the README lists as supported. NF is Windows only, so a single build does not cover both.

How leaf differs from Clash-rs and shadowsocks-rust

The closest comparisons are the other Rust proxy projects. shadowsocks-rust implements the Shadowsocks protocol family; leaf lists Shadowsocks as one of several protocols and adds Trojan, VMess, Vless, WebSocket, QUIC, Reality and its own AMux and MPTP transports on top. If Shadowsocks is all you need, shadowsocks-rust is a narrower and more focused target. If you need several protocols behind one engine and one library boundary, leaf's workspace is built for that.

Clash-rs is the other reference point. Clash-style clients are configuration-driven: the config file is the product surface, and the binary reads it. Leaf inverts that emphasis. The workspace makes leaf-ffi a first-class member alongside leaf-cli, and the README's transparent proxying table names iOS and Android, which are platforms where you link a library rather than run a daemon. The trade-off is visible in the documentation: leaf's README is a capability matrix, not a user manual.

A fourth option is to skip the framework and write the protocol handling yourself against a TLS and QUIC library. That only makes sense if you need one protocol and want no dependency on this project's abstractions.

Maintenance, licensing and the cost of tracking the workspace

The repository is not archived, and the last push was on 2026-09-10. Releases are versioned and recent: v0.14.0 on 2026-02-22, v0.14.1 and v0.14.2 both on 2026-02-25. The gap between the February releases and the September push suggests the project is still receiving commits without a matching tagged release, which is normal for a Rust workspace where the library and the CLI version independently.

Upgrade cost depends on which crate you consume. If you use leaf-cli, you track release tags and the CLI's own interface. If you link leaf-ffi, the C ABI is the contract, and any change to it is the thing to watch between versions. If you depend on leaf directly, you inherit the workspace's dependency graph, which for a proxy engine includes TLS, QUIC and two user-space TCP/IP stacks. Pinning a version and reading the diff before bumping is the practical approach; the README does not describe a stability policy for any of the three crates.

The licence is Apache-2.0, stated in the README and present as a LICENSE file at the repository root. Apache-2.0 is a permissive licence with an explicit patent grant, and it requires that you keep the licence and notice files when you redistribute. If you link leaf-ffi into a closed-source application, that is the clause to read with your own counsel; this is not legal advice, and the terms that matter are in the LICENSE file itself.

Editorial conclusion

Adopt leaf if you need proxy protocols inside your own binary through leaf-ffi or a custom crate, and you are willing to read the source because the README does not document configuration. Do not adopt it if you want a finished, config-file-driven client; the README gives no TOML or JSON config example. Before committing, verify the outbound-only gaps: VMess, Vless, Reality and Obfs have no inbound, and TPROXY is listed as coming soon.

Frequently asked questions

Official sources

1. eycorsican/leaf on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases