Espejismo

Español | Configuration | TUN Mode | Protocol | HK2/RK Benchmarks

Espejismo is a native Rust encrypted tunnel for running private client traffic through an authenticated remote egress server. It keeps the operational model small: one server binary, one local client binary, one TOML configuration file, and release archives that can be installed with a single command.

Server-side egress can also chain through an upstream proxy:

[remote.egress]
proxy = "socks5://user:pass@127.0.0.1:1080"
# proxy = "http://user:pass@127.0.0.1:8080"
# proxy = "https://user:pass@proxy.example.com:8443"

SOCKS4/SOCKS4a, SOCKS5, HTTP CONNECT, and HTTPS CONNECT are supported for TCP chaining. UDP chaining requires SOCKS5.

espejismo-remote runs on the VPS or server. espejismo-local runs on the client machine and exposes local SOCKS5/HTTP proxy ports or a native TUN interface for system-level IPv4 traffic capture.

In v0.1.5, TUN mode routes desktop TCP/UDP flows through interactive tunnel lanes by default and blocks UDP/443 locally unless configured otherwise, so browsers fall back from QUIC to TCP HTTPS instead of accumulating long UDP timeouts.

v0.1.5 also tightens lane observability and scheduling inputs: plain HTTP download-looking GET paths use bulk lanes, and admin per-lane byte counters include bytes from streams that are still active.

For live HK2 to RK mode data, including TCP, stealth, WebSocket, HTTP/2, and port hopping, see v0.1.3 HK2/RK mode matrix. For the adaptive lane scheduler and five-round median benchmark pass, see HK2/RK throughput tuning.

Linux, macOS, or Windows Git Bash:

curl -fsSL https://raw.githubusercontent.com/tianrking/Espejismo/main/scripts/install.sh | sh

Windows PowerShell:

iwr -useb https://raw.githubusercontent.com/tianrking/Espejismo/main/scripts/install.ps1 | iex

Installer inputs:

The installer only downloads and extracts the matching GitHub Release package. It does not create services, firewall rules, route changes, or hidden background processes.

Use configs/examples/espejismo.toml as the single configuration shape for both sides. The server reads [shared], [remote], [logging], and [admin]. The client reads [shared], [local], [logging], and [admin].

Minimum server/client edit:

[shared]
psk = "change-me-to-a-long-random-secret"

[shared.handshake_window]
enabled = true
step_secs = 30
previous_windows = 1
future_windows = 0

[shared.obfuscation]
profile = "stealth"
chunk_policy = "stealth"
randomize_chunks = false

[shared.stealth]
frame_size = 4096
frame_size_candidates = [3328, 3584, 4096, 4608]
tick_ms = 20

[local]
server = "YOUR_SERVER_IP_OR_DOMAIN:6690"
socks5_listen = "127.0.0.1:6680"
http_listen = "127.0.0.1:6681"

[local.tunnel_pool]
min_connections = 1
max_connections = 4
interactive_lanes = 2
bulk_lanes = 2

[remote]
listen = "0.0.0.0:6690"

shared.handshake_window derives the first-packet handshake key from the PSK and a short time slot, so recorded handshakes expire quickly. stealth frames hide stable payload lengths with fixed-size encrypted blocks. The tunnel pool spreads new logical streams across independent TCP lanes to reduce single-lane head-of-line blocking.

Run the remote side on the server:

~/.espejismo/bin/espejismo-remote --config ~/.espejismo/configs/espejismo.toml

Run the local side on the client:

~/.espejismo/bin/espejismo-local --config ~/.espejismo/configs/espejismo.toml

Then point applications at:

SOCKS5: 127.0.0.1:6680
HTTP:   127.0.0.1:6681

For system-level capture, start the client with TUN enabled:

sudo ~/.espejismo/bin/espejismo-local \
  --config ~/.espejismo/configs/espejismo.toml \
  --tun-enabled \
  --tun-auto-route \
  --tun-auto-dns

On Windows, run the terminal as Administrator. Official Windows release archives include bin/wintun.dll beside espejismo-local.exe.

cargo build --release
cargo test --workspace --all-targets

Main quality gates:

cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets

crates/espejismo-core     Shared protocol, crypto, config, admin, mux, transport
crates/espejismo-client   espejismo-local
crates/espejismo-server   espejismo-remote
configs/examples          One-file TOML example
docs/deployment           Configuration and operations docs
scripts                   Thin release download installers only

Use Espejismo only for systems and networks you own or are explicitly authorized to administer. Traffic shaping can reduce some stable fingerprints, but it does not make endpoint IPs, timing, uptime, traffic volume, or deployment mistakes invisible.