LianYaoHu

Documentation: https://lyh.maxlv.net/

LianYaoHu is a Rust CLI/TUI launcher for running Claude Code, Codex, or another code agent with a sanitized environment and a helper-managed network guard while forcing agent traffic through a selected VPN interface. macOS uses sandbox-exec plus PF on utun*; Linux uses Landlock/seccomp plus owner-scoped iptables/ip6tables rules on tun* or wg*.

Install

One line downloads the latest release for your platform, verifies its SHA-256, installs the lianyaohu and lyh binaries into /usr/local/bin, and installs the root firewall helper:

curl -fsSL https://lyh.maxlv.net/install.sh | bash

Prebuilt releases cover Apple Silicon macOS (aarch64-apple-darwin) and x86-64 Linux (x86_64-unknown-linux-gnu); on other platforms the installer tells you to build from source. Pass options after bash -s --, for example to skip the root helper or pin a version:

curl -fsSL https://lyh.maxlv.net/install.sh | bash -s -- --no-helper
curl -fsSL https://lyh.maxlv.net/install.sh | bash -s -- --version v0.1.3

Uninstall (removes the root helper, the hidden _lianyaohu group, and the binaries):

curl -fsSL https://lyh.maxlv.net/uninstall.sh | bash

Run directly during development:

cargo run -p lianyaohu-app -- --vpn utun5 -- claude
cargo run -p lianyaohu-app -- --vpn utun5 -- codex
cargo run -p lianyaohu-app -- --vpn tun0 -- codex

The same binary is also built under the short alias lyh, so once installed (cargo install --path crates/lianyaohu-app or by copying bin/lianyaohu/bin/lyh into your PATH) you can invoke it either way:

lianyaohu --vpn utun5 -- claude
lyh --vpn utun5 -- claude

By default it:

• prompts for a supported VPN interface at startup;
• requires the default IPv4 route to use the selected VPN interface;
• on macOS, applies sandbox-exec and a PF anchor scoped to the launched process group;
• on Linux, applies a Landlock/seccomp sandbox and iptables/ip6tables OUTPUT chains scoped to the launched process group;
• asks the root helper to run the agent as the caller's UID with the dedicated _lianyaohu effective GID;
• removes host-identifying environment variables and sets TZ=UTC;
• exposes the caller's $HOME, --cwd, and a per-launch temporary directory as writable, so agents can maintain their own state under $HOME;
• denies raw/system sockets, socket ioctls or kernel APIs, inbound sockets, and socket binding in the process sandbox (on macOS, loopback-only listeners are allowed so OAuth login callbacks and local dev servers work; on Linux all binds, including loopback, are denied);
• blocks LAN destinations and non-selected-interface egress for only the guarded agent tree.

Root Helper

Firewall enforcement and dedicated-group isolation require root. LianYaoHu uses a root helper at /var/run/lianyaohu-helper.sock to create/validate the hidden _lianyaohu group, install group-scoped firewall rules, drop the child to uid=caller_uid,gid=_lianyaohu while keeping the caller's normal supplementary groups, and launch the agent with the caller's stdio. On macOS the agent is spawned through launchctl asuser so it joins the caller's security session and keychain-backed credentials (Claude Code, gh, git credential helpers) keep working. The helper is installed as a LaunchDaemon on macOS and a systemd service on Linux.

Install the helper once:

scripts/install-helper.sh

Remove it:

scripts/uninstall-helper.sh

The helper authenticates requests with getpeereid, validates that the requested interface is an active utun, and supports the default session run path plus install, uninstall, and status for the current-UID fallback.

Because the child keeps the caller's UID, normal owner-based access to $HOME, the working tree, keychain, and TCC state behaves like the desktop user. The sandbox policy grants write access to $HOME so agent CLIs can maintain their own configuration and credential state.

For inspection without applying PF:

cargo run -p lianyaohu-app -- --vpn utun5 --print-profile
cargo run -p lianyaohu-app -- --vpn tun0 --print-profile
cargo run -p lianyaohu-app -- --vpn utun5 --print-firewall
cargo run -p lianyaohu-app -- --vpn tun0 --print-firewall
cargo run -p lianyaohu-app -- --vpn utun5 --no-pf -- claude
cargo run -p lianyaohu-app -- --vpn tun0 --shared-user-firewall -- claude

Validation

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test
scripts/e2e-linux-tart.sh

The unit tests validate policy generation, environment filtering, PF token parsing, route-output parsing, and selected runtime sandbox denials. The Linux Tart e2e boots an Ubuntu VM, installs the helper, creates a temporary tun0, and verifies group-scoped firewall, filesystem, and process-syscall enforcement around a real launched process.

Releases

Pushing a tag like v0.1.0 runs the release workflow. It verifies formatting, clippy, and tests, builds lianyaohu, creates a lianyaohu-<version>-<target>.tar.gz package, and attaches that package plus a SHA-256 checksum to the GitHub Release for the tag.

License

LianYaoHu is licensed under the MIT License.

Copyright (c) 2026 Max Lv.