A Rust-native, embeddable, multi-protocol proxy framework and CLI targeting practical and behavioral parity with Python pproxy.

• Nearly identical common CLI usage to pproxy
• Mixed-protocol listeners
• Arbitrary compatible multi-hop proxy chains
• TCP and UDP
• Secure defaults with explicit legacy compatibility
• Embeddable Rust library
• Pure Rust dependencies wherever practical
• Differential interoperability tests against Python pproxy
• Linux, macOS, and Windows support where the underlying capability exists

pip install eggress

See INSTALLATION.md for cipher extras, the opt-in top-level pproxy compatibility distribution, and supported Python versions/platforms.

curl -fsSL https://github.com/eggstack/eggress/releases/latest/download/install.sh | bash

This installs both the eggress and pproxy binaries from a version-aligned GitHub Release archive (default eggress-cli features). Windows uses install.ps1; pinned versions, custom directories, checksums, and troubleshooting live in INSTALLATION.md.

Verify with eggress version and pproxy --version. Standalone installs self-update with eggress update (GitHub Release binaries only; Python users update with pip).

cargo install eggress-cli --locked

For Rust users, unsupported prebuilt targets, Cargo-managed provenance, and custom features (e.g. ssh, quic, legacy-crypto). The workspace declares Rust MSRV 1.85. From a repository checkout: cargo install --path crates/eggress-cli. Lean and feature-gated build examples live in INSTALLATION.md.

[dependencies]
eggress-embed = "1"

From a repository checkout, substitute eggress-embed = { path = "crates/eggress-embed" }.

For listener-free outbound chains, enable ssh for native/TOML SSH upstreams. The pproxy-compat feature enables OutboundConnector::from_pproxy_uri(); pproxy-style SSH requires both features. The connector owns SSH session state internally and keeps native known-host verification separate from the explicit pproxy compatibility policy.

The embed SSH regression uses a temporary local OpenSSH server. Run it with EGRESS_REQUIRE_OPENSSH_TESTS=1 when validating an SSH-enabled build; CI installs openssh-server and treats fixture setup failures as test failures. The listener-free SSH OutboundConnector correction is available beginning with v1.0.7. Downstreams pinned to older releases must keep any SSH fallback until they upgrade to v1.0.7 or newer.

pip install eggress

# For AEAD cipher support:
pip install "eggress[cipher-api]"

The eggress wheel provides only the eggress package. For a bounded, Eggress-backed top-level pproxy import, additionally install the opt-in compatibility distribution from a repository checkout:

pip install ./python-pproxy-compat

Never install upstream pproxy and eggress-pproxy-compat together because they provide the same import namespace; uninstall upstream pproxy first.

Supported Python versions: 3.9, 3.10, 3.11, 3.12, 3.13. Prebuilt wheels available for Linux x86_64/aarch64, macOS x86_64/arm64, and Windows x86_64.

eggress -l http://:8080
eggress -l socks4://:1080
eggress -l socks5://:1080
eggress -l http+socks4+socks5://:8080
eggress -l http+socks5://user:pass@:8080
eggress -r http://proxy.example:8080
eggress -r socks5://proxy.example:1080
eggress -r socks5://hop1:1080__http://hop2:8080

SSH upstreams (opt-in, requires ssh feature):

cargo run -p eggress-cli --features ssh -- -r ssh://user:password@ssh.example:22
cargo run -p eggress-cli --features ssh -- -r ssh://user::/path/to/id_ed25519@ssh.example

The pproxy compatibility binary is also available:

pproxy -l http://:8080 -r socks5://proxy:1080
eggress pproxy translate -- -l http://:8080 -r socks5://proxy:1080
eggress pproxy check -- -l socks5://:1080 -r http://proxy:8080

See the operations guide for full CLI reference, TOML configuration, reload behavior, admin endpoints, and system-proxy integration.

Use eggress-embed to embed the proxy in another Rust application.

use eggress_embed::{EggressService, EggressConfig};

let config = EggressConfig::from_toml_str(r#"
    version = 1

    [[listeners]]
    name = "socks"
    bind = "127.0.0.1:0"
    protocols = ["socks5"]
"#)?;

let handle = EggressService::new(config).start_blocking()?;
let addrs = handle.bound_addresses();
println!("SOCKS5 listening on {}", addrs.listener("socks").unwrap());
handle.shutdown_blocking()?;

use eggress_embed::{EggressService, EggressConfig};

let config = EggressConfig::from_toml_str(r#"
    version = 1

    [[listeners]]
    name = "http"
    bind = "127.0.0.1:0"
    protocols = ["http"]
"#)?;

let handle = EggressService::new(config).start().await?;
println!("generation: {}", handle.status().generation);
handle.shutdown().await?;

match handle.reload_toml_str(new_config) {
    Ok(eggress_embed::ReloadOutcome::Applied { generation, upstreams }) => {
        println!("reloaded: generation={generation}, upstreams={upstreams}");
    }
    Err(e) => eprintln!("reload failed: {e}"),
}

let connector = eggress_embed::outbound::OutboundConnector::from_pproxy_uri(
    "socks5://127.0.0.1:1080__http://127.0.0.1:8080"
)?;

let (stream, info) = connector.connect_tcp("api.example.com", 443).await?;
assert_eq!(info.hop_count, 2);

from_pproxy_uri() accepts canonical __ multi-hop expressions, executes them in-process with no listener, and fails closed on unsupported hops. Requires the pproxy-compat feature.

Listener-free UDP (associate_udp) supports fixed-target direct and single-hop SOCKS5 relay over IPv4/IPv6 with idempotent close; composed/Shadowsocks UDP in this surface fail with structured errors. Native reverse control channels support opt-in server-authenticated TLS with optional mTLS ([[reverse_servers.tls]] / [[reverse_clients.tls]]); pproxy_compat wire remains plaintext.

[dependencies]
eggress-relay = "1"

For applications that only need to shuttle bytes between two already-connected Tokio duplex streams — no listeners, routing, TLS, or protocol handling — eggress-relay provides a small generic engine with an explicit half-close policy (HalfClosePolicy::Drain default) and directional errors. eggress-embed above remains the recommended way to embed a full proxy service.

See the Embed API reference for full API docs, lifecycle details, feature groups, and limitations.

from eggress import EggressService

toml = """
version = 1

[[listeners]]
name = "proxy"
bind = "127.0.0.1:1080"
protocols = ["socks5"]
"""

with EggressService.from_toml(toml).start() as handle:
    print("Listening on", handle.bound_addresses)
# service is shut down automatically

from eggress import start_pproxy

with start_pproxy(["-l", "socks5://:1080", "-r", "http://proxy:8080"]) as handle:
    print(handle.bound_addresses)

from eggress.pproxy import PPProxyService, Server

with PPProxyService.from_args(["-l", "socks5://:1080", "-r", "http://proxy:8080"]) as handle:
    print(handle.bound_addresses)

server = Server(listen="socks5://:1080", remote="http://proxy:8080")
server.start()
server.close()

See the Python bindings reference for full API docs, async support, Connection object, protocol/cipher objects, error model, and type stubs.

eggress maintains a behavior-oriented compatibility contract against the pinned pproxy==2.7.9 oracle (09d4752f17ed6787e1a073c93980eec019887ee3). Per-feature truth lives in the compatibility matrix and capability manifest; this section is a high-level summary only. Native Eggress capability does not automatically imply exact pproxy compatibility — the manifest/matrix status (matched, supported_difference, platform_limited, intentional_non_parity) is authoritative.

The bundled eggress.pproxy module provides URI-mode translation, CLI flag translation, compatibility routing, structured diagnostics, and differential tests. The optional eggress-pproxy-compat distribution provides the bounded top-level pproxy package backed by Eggress adapters.

• Trojan — client and server roles implemented natively; see the matrix for the status
• --daemon — Linux opt-in behind the pproxy-daemon feature; fails closed otherwise
• --sys — supported with warning; applies the bound local listener and restores prior settings
• SSH listeners — upstream-only; requires opt-in ssh feature
• QUIC/HTTP/3 — optional behind quic feature
• SSR — bounded TCP framing plus six built-in plugins behind opt-in pproxy-legacy
• Legacy ciphers — cast5-cfb, idea-cfb, rc2-cfb, seed-cfb are excluded; other legacy ciphers require legacy-crypto
• SOCKS4/SOCKS5 BIND — refused (pproxy 2.7.9 also requires CONNECT)
• TLS interception — HTTPS uses CONNECT tunneling, not MITM
• macOS PF transparent proxy — intentional non-parity

See the pproxy migration guide, compatibility matrix, and capability manifest.

See the full capability checklist for protocol, routing, UDP, TLS, Shadowsocks, Trojan, WebSocket, HTTP/2, reverse proxy, administration, and security status.

eggress/
├── crates/               # Workspace crates (core, cli, server, runtime, protocols, transport, etc.)
├── architecture/         # Per-component architecture deep dives + overview index
├── compat/               # Upstream oracle definition and fixtures
├── fuzz/                 # Fuzz harness smoke targets
├── benches/              # Criterion benchmarks
├── tests/                # Cross-implementation tests (tests/compat)
├── scripts/              # Helper and validation scripts
├── python/               # Canonical Python package source (python/eggress)
├── python-pproxy-compat/ # Opt-in distribution owning the top-level `pproxy` namespace
├── docs/                 # Documentation, parity manifests, and release artifacts