The network core for Mikan.
Citrus is a cross-platform proxy core maintained by Mikan. It combines local proxy listeners, encrypted DNS, TUN networking, and rule-based routing in one YAML configuration.
- HTTP, HTTPS, SOCKS, mixed, redirect, and TPROXY listeners.
- VLESS, Shadowsocks, Trojan, Snell, TUIC, Hysteria2, and other outbound protocols.
- TUN networking with a configurable network stack.
- DNS over HTTPS, TLS, and QUIC, with fake IP and DNS routing rules.
- Routing by domain, IP range, geodata, process, and logical rule combinations.
- Remote proxy and rule providers, health checks, fallback, and load balancing.
- HTTP and WebSocket controller APIs for compatible clients and dashboards.
| Branch | Role | Automated build |
|---|---|---|
main |
Primary branch | Prerelease-main |
dev |
Integration branch, all PRs | — (tested, not packaged) |
Build artifacts are available through GitHub Actions
and published builds through Releases.
Release files use the citrus-<os>-<architecture>-<version> naming scheme.
Start with the annotated configuration reference.
Citrus reads config.yaml from its configuration directory:
- Linux and macOS:
~/.config/citrus/, or$XDG_CONFIG_HOME/citrus/when configured. - Windows:
%USERPROFILE%/.config/citrus/. - Linux packages:
/etc/citrus/when started bycitrus.service.
Use -d to select a directory or -f to select a configuration file.
An existing configuration can be used by passing its directory explicitly.
citrus -d /path/to/config
citrus -t -f /path/to/config.yaml
citrus -vThe upstream configuration documentation describes the shared configuration format and controller API. Compatible dashboards include MetaCubeXD.
The module needs Go 1.26 or newer. Windows and macOS releases are built with the patched
MetaCubeX Go toolchain, which keeps Windows 7/8 and older
macOS working (not tested separately). Linux needs kernel 3.2 or newer. There are no separate
builds on old Go versions (-go120 and the like).
git clone https://github.com/getmikan/Citrus.git
cd Citrus
go mod download
go build -tags with_gvisor -trimpath -o citrus .
./citrus -vOn Windows, use -o citrus.exe and run ./citrus.exe.
The Go module path remains github.com/metacubex/mihomo. Internal package names and protobuf
namespaces follow upstream to make cherry-picks and pull request transfers easier.
The product, executable, and release assets are named Citrus / citrus.
go test ./...
go test -tags with_gvisor ./...The separate test/ module contains integration tests that require their external
services and Docker fixtures. CI disables optional external interoperability tests
with SKIP_INTEROP_TEST=1.
Core updates download Citrus assets from this repository.
The main and dev channels follow their respective prerelease builds; release
uses the latest tagged release. Automatic channel selection follows the running
binary's version. The legacy alpha channel name selects main for client compatibility.
Citrus is an independent fork of the MetaCubeX network core. The original Git history and contributor authorship are preserved.
The project builds on work from Dreamacro, SagerNet, v2fly, WireGuard, and the other dependencies listed in go.mod.
Citrus is distributed under the GNU GPL-3.0 license.