The core of Hiddify: sing-box (v1.15) with the protocols, transports and fixes that make it work on censored networks.
Documentation: docs/hiddify · فارسی. Every feature below has a page there, in English and Persian, with what it is, how it gets past filtering and every option. Upstream sing-box options are documented at sing-box.sagernet.org.
Everything here stands on sing-box, by nekohasekai (世界) and the sing-box contributors. The design of sing-box, its routing, DNS, inbounds and outbounds, TUN stack and the libraries around it (sing, sing-tun, sing-quic, sing-mux and more) make a fork like this possible at all. Hiddify keeps its changes small and close to upstream so it can follow every sing-box release. Thank you.
- WARP: Cloudflare WARP with no account setup, over
WireGuard, AmneziaWG or MASQUE, or
auto(the fastest that answers); an endpoint scanner with per-network scores and failover, noise presets and a noise search, a pool of registered devices that is only renewed when Cloudflare refuses one. - WARP scanner and noise: how the scanner, the noise presets (DNS, QUIC, SIP, random), the noise search and auto mode work together.
- WARP over MASQUE: the
masqueoutbound for WARP over HTTP/3 or HTTP/2, with a device already enrolled (device, no API); thewarpendpoint registers devices and takes a link's device asmasque.device. - AmneziaWG: AmneziaWG 3.1, with the QUIC masquerade.
- WireGuard additions: noise before handshakes (random, QUIC Initials, AmneziaWG-style DNS, QUIC and SIP templates), socket recovery, per-peer users.
- WireGuard outbound (legacy format).
- VLESS encryption, Sudoku, Mieru, TrustTunnel, SSH, Psiphon, DNSTT, MasterDNS, Soar, GooseRelay, Call tunnel, Tunnel, Bond.
- XHTTP, mKCP, XDRIVE, raw, custom gRPC paths, finalmask, Shadowsocks simple-obfs server, rmux.
- TLS fragment,
TLS tricks,
REALITY additions (post-quantum key share,
key_share, fragmentation, Firefox 148 and Safari 26.3 fingerprints), PROXY protocol.
- DNS group, bypass_if_failed, smart resolver pool, DNSCrypt (SDNS), sslip.io names, IPv6 by outbound.
- Balancer (round robin, lowest delay, consistent hashing, sticky sessions, sticky pool), fallback, URL test additions (more test URLs, failover mode, dial penalties), monitoring with a connection status for every outbound, unified delay.
Many crash, leak and stability fixes on top of sing-box, each with its commit: bug-fix log. What hiddify-app and hiddify-core need to know: app considerations.
git clone --recursive https://github.com/hiddify/hiddify-sing-box
cd hiddify-sing-box
make # Go 1.27.3 or newerThe forks of dependencies live under replace/ as git submodules, so clone with --recursive
(or run git submodule update --init --recursive). The default build tags are in the Makefile,
including the optional with_kcp, with_sudoku, with_bond, with_call and with_xdrive;
with_tailscale adds another optional feature.
Read AGENTS.md first; it holds for people and AI agents alike. In short: read the
Hiddify docs, keep changes to upstream files small (h_*.go files, //H on changed lines),
improve an existing feature rather than add an overlapping one, test, document in English and
Persian, list the feature here, and rebase on the latest v5 before opening a pull request. The
step-by-step procedure is the hiddify-feature skill.
Besides sing-box, this fork takes work from other forks and projects. Thank you to all of them:
- shtorm-7/sing-box-extended: the base of this fork, with AmneziaWG, WARP, tunneling, Mieru, XHTTP, SDNS, unified delay, mKCP, Sudoku, Bond, the call tunnel and the fallback group, and its forks of connect-ip-go, sing-dns and dnscrypt.
- Leadaxe/sing-box-lx: many fixes and specs, the
AmneziaWG 3.x masquerade, the DNS group modes, URL-test penalties and failover, the sticky pool,
REALITY
key_share, MASQUEvhttp, and utls-lx for the Firefox 148 and Safari 26.3 fingerprints. - reF1nd/sing-box: crash and stability fixes (Trojan, DNS deduplication and cache, Shadowsocks 2022, the HTTP transport, FakeIP, MASQUE, resolved).
- kyochikuto/sing-box-plus: the WARP endpoint scanner and QUIC noise, and TLS fragmentation methods.
- starifly/sing-vmess: VLESS encryption.
- Diniboy1123/usque and connect-ip-go: WARP over MASQUE.
- amnezia-vpn/amneziawg-go: AmneziaWG.
- refraction-networking/utls and metacubex/utls: TLS fingerprints.
- Psiphon-Labs: Psiphon.
- net2share/vaydns: DNSTT.
- masterking32/MasterDnsVPN: MasterDNS.
- getlantern/soar: Soar.
- kianmhz/GooseRelayVPN: GooseRelay.
- GFW-knocker: the WireGuard noise packets.
- XTLS/Xray-core: XHTTP, mKCP, XDRIVE, finalmask, VLESS encryption and REALITY, which the matching features here follow and are tested against.
- patterniha/Xray-core: the
mergefinalmask and theoobdial mode. - PoriyaVali/mirage: the
miragefinalmask (MIT).
Copyright (C) 2022 by nekohasekai <contact-sagernet@sekai.icu>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
In addition, no derivative work may use the name or imply association
with this application without prior consent.