Orange configuration.

Orange uses TOML format for configuration. The configuration file controls all aspects of the network engine including DNS resolution, proxy services, routing rules, and TUN mode settings.

Copy the bundled example to start from a known-good baseline, then edit as needed.

Every path in this reference resolves against one of two roots, and they are not the same directory. Files you supply resolve against the directory holding the config file. Files Orange manages for itself resolve against the state directory. Passing --config changes where the config is read from — it does not move the state directory.

Explicit overrides win in this order: --config <path>, then the ORANGE_CONF_PATH environment variable, then the default above. orange mesh init-server --public-endpoint <host> writes its generated config to the same default location, which --state-dir <path> or ORANGE_STATE_DIR can redirect.

A top-level integer, required in every config, that must appear before the first table. The runtime accepts only an exact match for the version it was built against — missing, older, or newer all fail at startup rather than being interpreted loosely.

Global settings for the Orange engine including logging and IP address family policy. Both log_level and ip_version are restart-required — a reload will report them rather than apply them, which is worth knowing before you try to raise the log level on a running process.

Where DNS queries enter Orange. Every listener lives under [listeners.*]; resolver behaviour is configured separately in [dns]. Changing a listener needs a restart — sockets and TLS are fixed at startup.

Per-source-address rate limiting on the DNS listener. Omit the table to leave it off.

Serve DoT to clients. Certificate and key paths resolve against the config file directory.

Serve DoH to clients, over HTTP/2 or HTTP/1.1. Both GET (RFC 8484 base64url parameter) and POST are accepted.

Three inbound proxy entry points, each with the same three fields. Mixed detects HTTP or SOCKS on a single port, so one listener can serve both. Proxy routing behaviour lives in [proxy.routing], not here.

How queries are answered, independent of where they arrive. The resolution order is: dns.rules reject or host mapping, then the hosts file, then MagicDNS when mesh is on, then Fake-IP, then cache, then upstream. Ports and TLS for the listener are in [listeners.dns].

IP-to-domain reverse lookup cache. Used by TUN mode to recover the original hostname from a destination IP so that domain-based routing rules and logging still work after DNS has been resolved. Set either threshold to 0 to disable.

DNS servers used to resolve infrastructure hostnames (upstream proxies, DoH/DoT providers, WireGuard endpoints). Bootstrap queries are forced to bypass the TUN tunnel and go out on the physical interface, preventing circular routing. Static hostname-to-IP mappings for infrastructure are now unified under [dns.rules].

Opts local-network domains (mDNS, LAN suffixes, service discovery) out of upstream DNS so they stay on the local link and do not leak to external resolvers. Matched queries return NoError + empty Answer (not NXDOMAIN) so that RFC 2308 negative caching does not block subsequent mDNS attempts.

Unified DNS routing table. The same rule set applies to every inbound (TUN, HTTP, SOCKS). Shorthand syntax covers reject and simple host mappings; the full { ... } form is required for DNS upstreams, conditional matches, and rewrites. Infrastructure hostnames (upstream proxies, DoH/DoT providers, WireGuard endpoints) should use { host = "..." } mappings here so they resolve without a circular lookup.

A value is either a shorthand string, a single object, or an array of objects evaluated top to bottom until one matches.

Rule values can be a shorthand string ("reject" or a literal IP hosts mapping), a single full-form object, or an array of objects evaluated top-to-bottom. Conditions use the when object; today the supported field is src (CIDR, supports negation with ! and multi-value with ,).

# Shorthand — reject
"*.ads.com" = "reject"

# Shorthand — hosts mapping
"example.com" = "127.0.0.1"

# Full form — hosts mapping
"example.com" = { host = "127.0.0.1" }

# DNS upstream
"@geosite:example-tag" = { to = ["9.9.9.9"] }

# Multiple upstreams (concurrent)
"example.com" = { to = ["8.8.8.8", "1.1.1.1"] }

# With specific outbound
"*.internal" = { to = ["10.0.0.53"], via = "wg-home" }

# Conditional rules (by source IP)
"*.corp" = [
  { when = { src = "10.0.0.0/8" },  to     = ["10.0.0.53"] },
  { when = { src = "!10.0.0.0/8" }, reject = true },
]

# Suffix rewrite — ask the router for .loc while the client queries .local
# rewrite requires a wildcard pattern (*.local / +.local) and must start with '.'
"*.local" = [
  { when = { src = "192.168.0.0/16" }, to = ["192.168.1.2"], rewrite = ".loc" },
]

# Default upstream (required)
"default" = { to = ["8.8.8.8"] }

Assigns virtual IPs from 198.18.0.0/15 to hostnames so that clients can start a connection immediately; Orange then recovers the hostname at the TUN/proxy boundary to make routing decisions. Best suited to TUN transparent proxy mode. IPv4 only — AAAA queries return empty responses, and the 198.18.0.0/15 range must not be used for anything else.

A container table. Everything that shapes proxy behaviour lives in its own sub-table: routing policy in [proxy.routing], outbound TLS and connection pooling under [proxy.outbound.*], upstreams and pools in their own arrays. Inbound ports and inbound authentication are not here — they are listeners.

Decides how ordinary proxy data flows are routed. This never changes how DNS queries themselves are resolved — the DNS listener, DoT and DoH paths are unaffected by anything here.

Connection reuse toward HTTP-based upstreams, so a new request does not pay for a fresh handshake.

TLS verification for connections Orange makes to upstreams.

When Orange runs in TUN or VPN mode, its own outbound traffic — bootstrap DNS, upstream proxies, mesh control and relay — must not be captured by the tunnel it just created. This section decides how those sockets escape. HTTP and SOCKS-only deployments never need it.

Each entry declares one upstream, named so that proxy.rules can reference it. Four types are supported: https, trojan, shadowsocks and wireguard. Any upstream can override the global probe with its own health_check block, or opt out with health_check = { disabled = true }. Changing this array requires a restart.

A CONNECT tunnel over TLS. Carries streams only — it has no datagram support, so a UDP flow matching a rule that points here is rejected with an ICMP Port Unreachable rather than being quietly re-routed. QUIC falls back to TCP on its own; UDP-only protocols such as NTP will fail.

[[proxy.upstreams]]
type = "https"
name = "https-1"

[proxy.upstreams.config]
addr = "http-proxy.example.com:443"
auth = "user:pass"

# Optional H2 pool tuning — every field must be >= 1
[proxy.upstreams.config.h2]
soft_max_age_secs = 120  # retire a connection, existing streams continue
idle_timeout_secs = 30   # mark unusable after this idle period
max_streams       = 100  # concurrent streams per connection
max_conns         = 2    # connections accepting new streams
ping_interval_secs = 30   # keepalive PING, sent even when idle
ping_timeout_secs  = 15   # PING timeout only stops new requests
ready_timeout_secs = 3    # wait for a connection to become ready
response_timeout_secs = 10 # wait for the upstream CONNECT response
forward_response_timeout_secs = 300 # HTTP forward; covers SSE and long polling

TLS with a fixed request header. Supports TCP and UDP; a UDP flow matching a Trojan rule automatically uses UDP ASSOCIATE, which makes DNS-over-Trojan and QUIC-over-Trojan work.

[[proxy.upstreams]]
type = "trojan"
name = "trojan-1"

[proxy.upstreams.config]
addr     = "trojan.example.com:443"
password = "your-password-here"
# sni = "trojan.example.com"   # only when the TLS name differs from addr

SIP022 only. Legacy Shadowsocks (AEAD-2017 and stream ciphers) is not supported and is rejected at startup. TCP and session-based UDP both work, with replay protection.

[[proxy.upstreams]]
type = "shadowsocks"
name = "ss-1"

[proxy.upstreams.config]
addr   = "ss.example.com:8388"
method = "2022-blake3-aes-256-gcm"
psk    = "<32 random bytes, base64>"
# udp = true

The configuration maps one-to-one onto a standard wg0.conf: [Interface] becomes config.interface, [Peer] becomes config.peer. One upstream describes one remote peer.

[[proxy.upstreams]]
type = "wireguard"
name = "wg-home"

[proxy.upstreams.config]
# mode = "auto"      # auto | userspace | kernel

# [Interface] — this machine
[proxy.upstreams.config.interface]
private_key = "<base64 or 64-hex>"
address     = "10.0.0.2/24"
dns         = "10.0.0.1"
# mtu = 1420         # 576-9000; lower for PPPoE or IPv6 transport

# [Peer] — the remote end
[proxy.upstreams.config.peer]
public_key  = "<remote interface public key>"
endpoint    = "vpn.example.com:51820"
allowed_ips = "0.0.0.0/0,::/0"

Groups several interchangeable upstreams under one name. A pool name can be used anywhere an upstream name can — proxy.rules to, proxy.routing.upstream, and dns.rules via all share one namespace, so a pool and an upstream may not have the same name.

Actively probes upstream latency and availability. Results feed metrics, /api/v1/proxy/upstreams/health, and pool member selection. The values here are the global default; any upstream can override them with its own health_check block, or opt out with health_check = { disabled = true }. The whole section is restart-required — the probe registry and interval are built once at startup, so /reload returns proxy.upstream_health with a non-zero status rather than applying a change.

Decides what each connection does: stay direct, take a tunnel, or be rejected. A rule has exactly two parts — a when object holding every match condition, and one action. Unknown top-level keys are rejected at startup, so match fields written outside when will not load.

# Exact domain — office intranet
[[proxy.rules]]
when = { domain = "api.internal.corp" }
to   = "wg-office"

# Subdomains only — the apex ads.example.com is not matched
[[proxy.rules]]
when   = { domain = "+.ads.example.com" }
reject = true

# Several conditions in one when: same name, two paths by location
[[proxy.rules]]
when   = { domain = "*.home.lab", src = "192.168.1.0/24" }
direct = true

[[proxy.rules]]
when = { domain = "*.home.lab" }
to   = "wg-home"

# Dataset tags and ports use the same when object
[[proxy.rules]]
when   = { geoip = "private" }
direct = true

[[proxy.rules]]
when   = { port = "22" }
direct = true

# A broad private-range rule isn't worth a lookup of its own.
# Under on_demand, resolve_ip = false keeps it from triggering one.
[[proxy.rules]]
when       = { ip_cidr = "192.168.0.0/16" }
resolve_ip = false
direct     = true

# Fallback: no when at all — moved to the end automatically
[[proxy.rules]]
direct = true

System-level network gateway over a virtual interface. Captures all OS-level traffic and feeds it into the routing engine. Requires admin privileges on Linux/macOS and is not supported on Windows. SNI/HTTP sniffing lives in its own section.

Extracts TLS SNI or HTTP Host from the first bytes of a TCP connection so that domain-based routing rules still work when only an IP destination is visible. Sniffing requires the client to speak first; enabling it on server-first protocols (MySQL, SMTP, SSH) introduces timeout delays. The default port allow-list keeps it limited to HTTP/HTTPS-style traffic.

Connection and idle timeouts for proxy inbounds. TUN has its own idle settings under [tun], deliberately separate — a TUN connection holds far larger buffers than a proxy tunnel does. Both fields are restart-required: the proxy servers capture them at startup, so a reload would report success while the old values stayed in force.

One local HTTP surface for health, metrics, live streams, request traces, mesh administration, and configuration reload. It binds to a loopback address only — a non-loopback bind is rejected at startup — and every route requires a bearer token. There is no TLS, no trusted-proxy mode, and no way to turn authentication off; for remote access, use an SSH tunnel.

TOKEN=$(cat /var/lib/orange/admin.token)

curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:9898/readyz
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:9898/metrics
curl -N -H "Authorization: Bearer $TOKEN" http://127.0.0.1:9898/api/metrics/live
curl -X POST -H "Authorization: Bearer $TOKEN" http://127.0.0.1:9898/api/v1/reload

Records the lifecycle of each request — matched rule, route decision, connect timing, DNS answer source, failure class — and streams it to subscribers over WebSocket.

Controls how trace events are aggregated before being delivered to WebSocket subscribers. Tighter flush intervals reduce end-to-end latency; larger batches reduce frame overhead.

Adaptive protection for memory-constrained environments (e.g. iOS NetworkExtension's ~50 MB limit). A background monitor samples how much memory Orange has allocated and applies tiered mitigations as thresholds are crossed, so the OS does not kill the process outright.

[memory_pressure]
warning_bytes     = 31457280   # 30 MB
critical_bytes    = 39845888   # 38 MB
emergency_bytes   = 46137344   # 44 MB
check_interval_ms = 5000

GeoSite and GeoIP datasets classify large numbers of domains and IP ranges under a tag, so a rule can name one tag instead of listing thousands of entries. Local paths resolve against the config file directory; HTTP(S) URLs are downloaded on first use. Orange bundles no dataset and recommends no particular publisher — bring a Protobuf-format dataset you trust, and reference whichever tags it defines.

[dataset]
geosite = [
  "./GeoSite.dat",
  "https://datasets.example.com/geosite.dat",
]
geoip = [
  "./GeoIP.dat",
  "https://datasets.example.com/geoip.dat",
]

Mesh is a top-level subsystem alongside DNS and Proxy — not a proxy upstream. It gives every joined device a stable private IPv4 address and a name that resolves inside your network, carries traffic over WireGuard on the TUN packet path, and upgrades a pair to a direct peer-to-peer path once that path has been verified — your own relay carries the traffic until then, and again if the path degrades. Every field here requires a restart; /reload reports them and applies nothing.

Required when roles contains control. Control issues identities and addresses, distributes the signed peer map and ACL policy, approves subnet routes, and signs relay tickets. It holds no session keys and never sees payload. In v1 control must run in the same process as relay.

Required when roles contains relay. The relay is a dumb forwarder: it moves sealed WireGuard packets between peers, holds no session keys, cannot decrypt payload, and does not trust a client's self-reported identity — the binding comes from the authenticated session. It is the availability floor beneath the direct path, not the normal data route.

How fast the UDP sidecar pushes data frames. Restart required.

Peers discover each other's public address through a first-party STUN server that the control node runs itself — no third-party STUN service is involved. A path is promoted to direct only after the same endpoint completes repeated signed probe round trips within a short verification window; until then, and whenever the path degrades, traffic rides the relay. Device type never influences this: a phone-to-phone pair is evaluated exactly like any other.

Mesh payloads are encrypted with WireGuard end to end between peers. Decryption alone doesn't grant access: after a packet is decrypted, its inner source address must belong to that peer's mesh address or an approved subnet before access control is even evaluated. Tunnels are created per peer on first use.

With no rules configured, every registered peer can reach every other peer. Adding a single rule flips the network to explicit-only: anything unmatched is denied, with no implicit fallback. Rules are authoritative only on the control node — the same tables on an edge are inert templates. Changing them requires a restart; for an urgent cutoff, disable the node online instead.