Hysteria2 realm listener — mihomo

A Hysteria2 realm listener hosts multiple Hysteria2 "realms" — tenants — behind one endpoint. Each realm is an independent Hysteria2 service multiplexed onto the same listening address, distinguished by realm identity rather than by a separate port. Clients reach a realm by setting realm-opts on their ordinary Hysteria2 proxy: they point at this listener's control endpoint, present the shared token, and name the realm they want to join.

This is the server side of the realm feature. Realm support is newer and advanced — most deployments run a plain hysteria2 listener instead.

Listener

Entry under listeners: with type: hysteria2-realm. Embeds BaseOption (listen, port).

Field	Type	Default	Allowed values	Description
token	string	(unset)	<string>	Shared auth token realms must present to register with / be served by this listener.
max-realms	int	0	<int>	Maximum number of realms this listener will host. 0 leaves it unbounded.
max-realms-per-ip	int	0	<int>	Per-client-IP cap on hosted realms. 0 leaves it unbounded.
trusted-proxy-header	string	(unset)	<header name>	HTTP header carrying the real client IP when the listener sits behind a fronting proxy.
realm-name-pattern	string	(unset)	<pattern>	Pattern constraining accepted realm names.
certificate	string	(required)	<PEM file path>	TLS server certificate (PEM path).
private-key	string	(required)	<key file path>	TLS private key.
client-auth-type	string	(none)	no-client-cert | request-client-cert | require-any-client-cert | verify-client-cert-if-given | require-and-verify-client-cert	Mutual-TLS client-auth mode (e.g. `require-and-verify-client-cert`).
client-auth-cert	string	(unset)	<PEM file path>	CA bundle accepted as client roots.
ech-key	string	(unset)	<ECH config>	Encrypted Client Hello key material.
alpn	[]string	[h3]	h3	ALPN offered during the TLS handshake (typically `h3`).

Source: listener/inbound/hysteria2_realm.go:12-25 · pinned at v1.19.27 (5184081)

Example

Minimal realm listener with a shared token and a per-IP realm cap:

listeners:
  - name: hy2-realm-server
    type: hysteria2-realm
    listen: 0.0.0.0
    port: 443
    token: <realm-token>
    max-realms: 16
    max-realms-per-ip: 2
    certificate: /etc/mihomo/server.crt
    private-key: /etc/mihomo/server.key
    alpn: [h3]

A client joins a realm on this listener by adding realm-opts to its outbound — see Hysteria2 — mihomo.

Notes

• token is the shared secret. A client's realm-opts.token must match it for that client to register with, or be served by, the listener.
• max-realms bounds the total number of realms the listener will host; max-realms-per-ip bounds them per client IP. Leave both at their default to keep them unbounded.
• trusted-proxy-header only matters when the listener sits behind a fronting proxy that rewrites the source address — it names the header that carries the original client IP so per-IP caps stay accurate.
• TLS is mandatory: supply certificate and private-key. Add client-auth-type plus client-auth-cert to require mutual TLS, and ech-key to enable Encrypted Client Hello.

Cross-core notes

• Realms are a mihomo / Hysteria2 feature. Neither Xray-core nor sing-box exposes an equivalent multi-realm listener — each hosts a single Hysteria2 service per inbound. See Hysteria2 — Xray-core and Hysteria2 — sing-box for their single-tenant listeners.

Source: listener/inbound/hysteria2_realm.go:12-25 · v1.19.27 (5184081)