Run the Orange mesh on your own server.

Every mesh networking tool needs a server: one that verifies device identity and relays traffic when two devices cannot connect directly. That means users must trust someone—not to log their activity, inspect their traffic, or interrupt the service at the moment it matters most.

We do not believe that trust should be the only option.

Orange traffic is end-to-end encrypted between devices. The server only coordinates connections and relays traffic; it cannot see the contents. That is enforced by the architecture and does not depend on who owns the server. But “we cannot see it” and “you can verify for yourself that nobody can see it” are ultimately two different things.

That is why we make the complete server available as a free download. You can deploy it on your own machine and keep the entire path under your control—privacy and control guaranteed by architecture, not by a promise.

We want you to choose Orange because it works well, not because you have no other choice.

The server has two responsibilities: managing enrollment and relaying data. It verifies device identity, assigns virtual IPs, distributes the device list and access policy, and forwards ciphertext when devices cannot connect directly.

Traffic starts on the server relay and moves to a direct peer-to-peer path once that path has proven itself, returning to the relay if it degrades. Seeing traffic on the relay is not a failure—it is the path that keeps the mesh usable in every network environment.

Devices on the same network can find each other without any help. For two devices on different networks to establish a direct path, the server has to help them discover their public addresses—see Improve direct-path success. Until you enable that, expect most cross-network traffic to stay on the relay.

Each enrolled device receives a stable virtual IP that remains unchanged across restarts, Wi-Fi changes, and travel. Devices can then reach one another as if they shared one local network.

Deployment takes about ten minutes and normally requires very little maintenance afterward. A single server is recommended for no more than 100 devices.

• A Linux host. The binary also runs on macOS, but the systemd steps in this guide must be replaced with launchd.
• A public IPv4 address, or a domain name that resolves to the host.
• Accurate system time through NTP or chrony. Clock drift causes certificate and credential validation failures that are otherwise difficult to diagnose.

Initialization writes 172.31.240.0/20, which provides roughly 4,000 addresses and stays clear of the ranges most networks already use. Once a device has joined, do not change this range—it is part of the mesh's network identity, and changing it means enrolling every device again.

Before initialization, confirm that it does not overlap another VPN, a cloud VPC, Docker or Kubernetes, your office or home LAN, or the reserved 198.18.0.0/15 range. Tailscale, for example, commonly uses 100.64.0.0/10.

To use another range, pass --address-pool <CIDR> to the initialization command, for example 10.90.0.0/16. The host bits must be zero—use 10.90.0.0/16, not 10.90.0.5/16—and the prefix must not be narrower than /30.

Pass only a hostname or IP address to --public-endpoint—do not include a port or an http:// prefix.

Initialization creates the configuration, admin credentials, and TLS certificate under /var/lib/orange/. It also prints a bootstrap join credential.

Confirm that 8088/tcp, 51820/tcp, 51821/udp, and loopback-only 9898/tcp are listening.

The warning should disappear and Warnings should return to zero.

The command writes a one-time .omesh file and prints its path. Transfer that file to the user and import it in the Orange client. The device receives a stable virtual IP when enrollment completes.

The permissions requested by a device must match the join credential. A normal edge credential cannot enroll a gateway.

The command output also includes a CLI enrollment example for enrolling from the command line on a server. Orange app users only need to import the generated file and do not need to run that command.

The node list includes device ID, virtual IP, name, roles, and online state. A device with no heartbeat for more than 90 seconds is shown as offline.

A unique prefix of a device ID is sufficient, such as a3f2.

• Revoking a join credential only affects unused enrollments. Disable a device that has already joined.
• Removing a device releases its name. If ACL rules reference that name, another device could inherit those permissions. Update and restart the policy before removal.

Create the first backup immediately after enrolling your first group of devices.

The restored certificate remains valid and does not need to be regenerated.

Use the Ready field to judge server health. A running process by itself is not proof that control and relay services are usable.

All settings from this point are optional. The generated defaults already work. Restart Orange with sudo systemctl restart orange after changing /var/lib/orange/config.toml.

By default, every registered device can reach every other device. Add ACL rules when only specific users or groups should reach a service.

from may name a group or a device. to may target a device name or subnet followed by a port. Supported protocols are tcp, udp, and icmp-echo; set via to the gateway device name when the destination is a LAN behind that gateway.

Change ports only when the defaults conflict with another service or are blocked by the network. Complete this before production enrollment; existing devices retain the old ports and must be enrolled again after a change.

Choose a non-default admin port during initialization with --admin-port. Every later admin command must then include --admin-port <port>.

Enable STUN assistance when peers sit behind different carriers or complex NATs and too much traffic falls back to relay. Open 3478/udp on the server.

Enable the matching option in the Orange client. A failed direct attempt does not break connectivity; traffic automatically remains on the relay.

Use bandwidth pacing when the host has ample bandwidth but measured relay throughput remains below the available link capacity.

The example targets 100 Mbps. A reasonable starting value for burst_bytes is target_bps ÷ 400. Tune against your own measurements; the example is not a performance guarantee.

If UDP is completely unavailable, add relay_udp_sidecar_enabled = false under [mesh] to use TCP only.

The default self-signed certificate is secure because each join credential carries its fingerprint. Replacing that certificate later, however, requires new join credentials for every device. A trusted certificate avoids that operational cost.

The private key must be a regular file owned by the Orange service user, mode 0600, inside a mode 0700 parent directory. Let's Encrypt's live/ entries are symlinks, so copy the key to a protected regular file first.

Adjust the owner to whichever user runs Orange on your host. Certbot runs every executable in that directory after a successful renewal.

The default is /var/lib/orange. Commands run with sudo and commands run as a normal user resolve state differently, so always operate the server under the same identity. To use another path, add --state-dir <path> to every command.

The admin API remains on loopback. Run management commands through SSH instead of exposing it publicly.