The network core of Mikan
Citrus is the core of the Mikan VPN service, a fork of mihomo. It speaks Xray, post-quantum REALITY, XHTTP and ECH included; keeps per-user traffic, limits and events; builds cascades and exports metrics. Same configuration as mihomo. GPL-3.0.
citrus -d ~/.config/citrusOne binary for Linux, Windows, macOS, FreeBSD and Android.
Why a core of its own
Mikan is a VPN service: on its nodes the core runs as a server for many users at once. mihomo was written as a client, and much of what a node needs is not there. Citrus puts it into the core itself.
Xray compatibility
Post-quantum REALITY (X25519MLKEM768 and ML-DSA-65) on the client and the server, XHTTP with Xray’s behaviour and defaults, ECH keys and links in Xray’s formats. Automated tests check all of it against Xray v26.10.10.
Users are part of the core
Per-user traffic and online addresses, limits on speed, connections, addresses, quota and expiry, and inbound users changed without a restart. Through REST, the Go API and the /events stream.
A hardened server
A security review, a code review and a static audit: a controller without a secret stays off the network, pre-authentication state is bounded, every request is authenticated, updates are checked against checksums.txt, CI is pinned by digest.
Cascades
A type: chain group builds an entry → exit chain from proxies and groups, and its health check names the hop that broke.
Observability
Prometheus /metrics, /healthz and /readyz probes, events for rejected authentication and JSON logs for Loki and ELK.
Less to carry
VMess, SSR, Hysteria v1, TUIC v4, Shadowsocks stream ciphers, v2ray-plugin and mKCP are gone: about 20 thousand lines the service does not need.
Citrus and mihomo
The configuration format and the controller API are shared with mihomo, and mihomo clients connect to a Citrus server. The table lists only what has already landed in Citrus.
| Citrus | mihomo | |
|---|---|---|
| Post-quantum REALITY | X25519MLKEM768 by default, ML-DSA-65, server-side require-x25519mlkem768 and mldsa65-seed | X25519MLKEM768 only behind a flag, no ML-DSA-65 |
| User stats | Traffic and online IPs per inbound and user, query with reset | Global totals only |
| User limits | Speed, connections, addresses, quota, expiry | None |
| Inbound users | Changed through REST, the listener stays up | Only by reloading the config |
| Events and metrics | /events (WebSocket, SSE, NDJSON), /metrics, /healthz, /readyz | None |
| Cascades | A type: chain group with a check of every hop | dialer-proxy only |
| Controller on a network address | Only with a secret | Starts without one |
| Self-update | The package is checked against the release’s checksums.txt | No check |
| Legacy protocols | Removed | Present |
What it does
Inbound
HTTP, HTTPS, SOCKS, mixed, redirect and TPROXY. Plus server listeners for VLESS, Trojan, Hysteria2, TUIC, AnyTLS and more.
Outbound protocols
VLESS with REALITY, Trojan, Shadowsocks, Hysteria2, TUIC, AnyTLS, TrustTunnel, Snell, WireGuard and more.
TUN
All system traffic through the core, with a configurable network stack.
DNS
DNS over HTTPS, TLS and QUIC, fake IP and routing rules for DNS queries.
Rules
Routing by domain, IP range, geodata, process and logical combinations of rules.
Providers and groups
Remote proxy and rule providers, health checks, fallback and load balancing.
Controller API
HTTP and WebSocket APIs compatible with mihomo clients and dashboards such as MetaCubeXD.
Download
Builds are published as GitHub releases. Files are named citrus-<os>-<arch>-<version>: in a release the version is the tag (citrus-linux-arm64-v1.2.3.gz), in a prerelease the branch and commit (citrus-linux-arm64-main-1a2b3c4.gz). Windows builds are .zip; Linux also gets .deb, .rpm and .pkg.tar.zst.
| Channel | Built from | What it is |
|---|---|---|
release | The latest vX.Y.Z tag | Stable versions. |
Prerelease-main | The main branch | A build of every merge into main. |
The amd64 file targets x86-64-v3 (Intel Haswell, AMD Excavator and newer); for older ones take amd64-compatible (v1) or amd64-v2. There are also arm64, armv5–v7, 386, mips, riscv64, loong64, s390x and more.
Citrus and Mikan
Mikan is a free VPN panel. Its nodes embed the core as a library and count traffic per user on every connection; today that is mihomo, and Citrus is next. The core lives in its own repository so it can be used without the panel too: as a regular mihomo-style client or server.
Documentation
Getting started
Download, add a config, run.
Migrating from mihomo
What to change and what to expect.
Compatibility
mihomo and Xray clients with a Citrus server.
Roadmap
What is done and what is next.
Changelog
Every merged pull request, by area.
Security
How to report a vulnerability.
News
Second beta — faster upload and download, lower latency under load
v1.0.0-beta.2 — a comparison with Xray, sing-box and mihomo on one host, faster download, latency under load, tunnel memory, TUIC, smux and quota fixes.
Audit closed, cascades, events, unix sockets and DNSCrypt
The week in dev — the audit fixes, chain groups, the /events stream, listeners on a unix socket, DNSCrypt and tests with mihomo clients.
Post-quantum REALITY, faster XHTTP through CDNs, and a protocol cleanup
Merged into dev — post-quantum REALITY on the client and server, faster packet-up through CDNs, legacy protocols removed, a rejected-auth hook and race fixes.