honk

English | 中文

honk is an experimental Rust transparent-proxy engine for Linux. Its eBPF datapath and configuration syntax are inspired by dae; its outbound groups, multi-protocol dialers, and Clash-compatible API follow sing-box designs. It is an independent implementation, not a line-for-line port.

Early alpha, not recommended for production. Expect breaking changes, incomplete features, and limited real-world validation.

Capabilities

Transparent TCP/UDP: LAN-forwarded and host-originated traffic through TC eBPF, dae0/daens, and compiled routing on Linux 6.12+.
Outbounds: SOCKS5, Shadowsocks/2022, Trojan, AnyTLS, Hysteria2, TUIC, Juicity, VMess, and VLESS, plus built-in direct and block. Trojan/VMess/VLESS support the H2 XHTTP profile (packet-up, stream-up, stream-one); VMess remains TCP-only. Protocol-specific limits are in the node reference.
Groups: Selector, URLTest, LoadBalance, Fallback, and Score. Score uses business observations and bounded validation; select it with policy: score. Omitted policy remains Selector. See the group reference.
DNS: UDP, TCP, DoT, DoH, DoQ, and DoH3 upstreams, optionally through a node or group, with routing and caching.
Configuration and control: dae syntax, subscriptions, reload, a Clash-compatible REST/WebSocket API, and the honk-tool CLI toolbox.

Implemented does not mean fully reviewed; see review status. There is no FakeIP engine, full mihomo parity, or Windows/macOS datapath.

Getting started

Real transparent proxying requires root, Linux 6.12+, the required kernel options, and bpffs. Initial deployment changes network hooks, namespaces, and sysctls; keep an out-of-band management path available.

Follow the startup guide for kernel checks, installation, a direct-only configuration, and connectivity verification.
Download a matching binary from Releases; each release's Downloads section explains every archive, and SHA256SUMS verifies it. Or follow the guide's source-build prerequisites. Release binaries embed the eBPF object; source builds require the ebpf feature. Plain cargo build --release does not enable the real datapath.
Add nodes, groups, routing, and DNS using the configuration guide. The repository provides full and minimal development examples; adapt interfaces and node addresses before use.

The documentation index links all bilingual guides, references, and subsystem designs. Start with the architecture overview, node reference, or API reference for details.

Operational notes

UDP NFQUEUE is enabled by default: it holds ambiguous LAN-forwarded first packets before conntrack/NAT. Set global.nfqueue_enable: false to disable it; changing this setting requires a restart. Mock mode, builds without ebpf, or an unavailable queue disable staging for that process with a warning. honk exclusively owns queue 320 and nftables inet honk_nfqueue / udp_decision; same-namespace firewall managers must not modify them. See the NFQUEUE design.
VLESS upgrade: vless_mode is removed and all VLESS node IDs are re-derived. Migrate static links and cached/provider content before upgrading, especially offline; keep usable name-based Selector choices and persisted delay samples. UDP permission, packet encoding, and multiplexing are independent settings. See the migration guide and VLESS design.

Opt-in native observation API

Build with --features native-api (the full and -native-api release artifacts include it) and configure experimental.native_api for independent observations and controls on 127.0.0.1:9527: bounded flows/logs/DNS history, probes, provider status/refresh, per-network Selector control and exact connection closure. Captured .dae sources remain authoritative, with opt-in source/Group PATCH transactions, synchronous main-file node/provider creation and removal, and verified-geodata operations; existing entries are edited through source PUT. --store db records accepted sources as revisions in a state database instead. A bearer secret or password login is required unless anonymous loopback is explicitly enabled. Serve a trusted directory, or build --features native-ui and set ui: embedded for the pinned doona build without runtime downloads. Native runtime_mode and full kernel transparency remain unavailable. See native settings and the API contract.

Versions and compatibility

Releases follow SemVer from v0.1.0; tags with -alpha.N, -beta.N or -rc.N are prereleases. Before 1.0, a minor release may change configuration or behaviour, and its notes list what needs action before upgrading.
Requirements: root and Linux 6.12+ with the kernel options in the startup guide, on x86_64 or aarch64 with gnu or musl.
Configuration uses dae syntax, documented in the configuration guide.
The native API is served under the fixed /api/v1 base and stays opt-in through experimental.native_api; before 1.0 it may change in a minor release. GET /api/v1/version reports the contract identity.
Each release lists its archives in a Downloads section and carries SHA256SUMS and build provenance. Security reports go through the security policy.

Development

The workspace contains configuration, shared eBPF types, NFQUEUE, outbound, core, and tooling crates. The kernel program in crates/honk-ebpf is built separately. Build prerequisites and commands are in the startup guide and Justfile.

For unprivileged userspace development, use mock mode. --mock-ebpf does not intercept traffic and is not a datapath test.

Debug builds

Between releases, maintainers publish debug.* builds from main: release-profile binaries for testing, not Cargo debug-profile builds. The rolling Debug prerelease always holds the newest one and is never marked Latest; each debug tag also keeps its own release: the nine newest other tags plus the tag a re-run has just updated. Like formal releases, they carry SHA256SUMS, build provenance and a Downloads section. Publication details are in the release rules.

Review status

Most userspace subsystems were largely AI-authored with partial maintainer review; the maintainer's primary focus is eBPF. These checkboxes record maintainer review, not feature availability:

eBPF routing, maps, and semantics
Control plane
AnyTLS / Shadowsocks (including 2022) / SOCKS5
RPRX (VLESS / XTLS / XHTTP / WSS / REALITY) exclude XHTTP
Trojan-GFW (needs UoT implementation)
DNS logic
Configuration parser (dae extensions)
Reload logic
Tooling

No test.1 release tag will be published until all currently unreviewed code has been reviewed and any unverified AI-generated implementation has been addressed.

TODO

Evaluate AF_XDP and XDP paths for further performance gains
Add a honk-specific REST API beyond Clash compatibility
Add inbound support

Track other work in Issues and Discussions.

Acknowledgments

dae / daed-rs: eBPF transparent proxy lineage
sing-box: outbound group and Clash API patterns
daeuniverse/outbound: protocol reference
juicity-rs by Markson Pigeonzilla Plus: Juicity protocol reference, wire-format alignment, and live interop testing
aya-rs: Rust eBPF

License

SPDX-License-Identifier: GPL-3.0-only
Copyright (c) 2025, glassyiris <honk@catmint.cc> and honk contributors

The development-only dae parser oracle links dae (AGPL-3.0-only). It is never shipped or linked into honk-core.