Ultra Mesh Network is a small, user-space mesh for macOS. Every running laptop gets a stable IPv6-looking overlay address, discovers nearby nodes over regular Wi-Fi and Apple peer-to-peer Wi-Fi, and can relay encrypted traffic for nodes that are not directly connected.

It does not install a virtual network interface or replace normal IP networking. Use umn ping, the text commands, or the local SOCKS5 proxy to reach mesh addresses.

Requirements and installation

macOS 14 or newer
Apple Command Line Tools with Swift 6
Wi-Fi enabled on both Macs

Copy this project to each laptop and run:

./scripts/test.sh
./scripts/install.sh
umn status
umn address

The installer builds locally, copies umn and umnd to ~/.local/bin, and starts umnd as a per-user LaunchAgent. It never needs root. If prompted, allow local-network access. The identity and configuration live in ~/Library/Application Support/UltraMesh.

Use ./scripts/uninstall.sh to remove the binaries and LaunchAgent. It deliberately preserves the identity so reinstalling keeps the same mesh address.

For development, run swift run umnd in one terminal and swift run umn status in another.

Text communication

On the receiving laptop:

umn address
umn firewall allow 7000 --from any
umn text listen 7000

On the sender:

umn ping <receiver-mesh-address>
umn text send <receiver-mesh-address> 7000 "hello over the mesh"

Replace any with a specific mesh address to restrict the port. Opening a firewall port is not sufficient by itself: a local service must also be bound. When umn text listen exits, the binding disappears but the firewall rule remains.

Useful diagnostics:

umn peers
umn routes
umn firewall list
umn alias set alice <mesh-address>
umn ping alice.mesh

Aliases are stored locally and are not claimed network-wide.

HTTP and HTTPS

Run a local server and expose it on a logical mesh port:

# Host laptop
python3 -m http.server 8080 --bind 127.0.0.1
umn firewall allow 80 --from any
umn expose 80 --to 127.0.0.1:8080

Start the client-side proxy:

umn alias set host <host-mesh-address>
umn proxy --listen 127.0.0.1:1080
curl --proxy socks5h://127.0.0.1:1080 http://host.mesh/

The proxy implements SOCKS5 CONNECT and binds only to loopback. A browser can use the same proxy after its SOCKS settings are pointed at 127.0.0.1:1080 with proxy-side DNS enabled.

HTTPS is passed through unchanged. The web server remains responsible for its TLS certificate, and a self-signed certificate will still produce the usual trust warning.

Design and current limits

Bonjour and Network.framework discover peers over infrastructure and Apple peer-to-peer Wi-Fi (includePeerToPeer). New routes recover automatically when an access-point path disappears while Wi-Fi remains enabled.
Signed link-state announcements and shortest-hop routing support multi-hop topologies. The implementation is bounded and tested for 32 live nodes and 16 hops.
Service payloads are authenticated and encrypted end-to-end with Curve25519, HKDF-SHA256, and ChaCha20-Poly1305. Relays see routing metadata but cannot read ports or content.
Streams use sequence numbers, acknowledgements, retransmission, and a 60-second recovery window. An active stream can continue after a route change if another path appears within that window.
The endpoint firewall defaults to ping-only. Transit traffic is relayed independently of endpoint firewall rules.
Text is limited to 4 KiB. A logical stream is limited to 1 MiB total and the daemon supports at most 32 simultaneous streams.
There is no durable offline queue: a new operation with no live route fails immediately.
Membership is open. Identities are self-authenticating, but there is no global authority, revocation service, or Sybil resistance yet.
Apple peer-to-peer Wi-Fi works only between Apple devices. The documented mesh protocol is transport-independent so other bearers can be added later.

The on-wire details are in docs/protocol.md.