Technical Specification

Architecture & Wire Protocol

LocalMetro is built around a lean, open, length-prefixed JSON protocol over standard TCP. No proprietary cloud stacks.

Engineered Open

Protocol & Connection Architecture

Zero proprietary black boxes. LocalMetro uses standard length-prefixed JSON frames over raw TCP sockets, advertised over mDNS and UDP.

4-Tier Connection Fallback (ADR-010)

LocalMetro tries faster and more direct physical links first before falling back to network broadcasts:

Tier 1: Wired USB Tethering0.2ms Latency

Direct USB-C cable link (192.168.42.x subnet). Works in airplane mode, zero Wi-Fi interference, maximum transfer speed.

Tier 2: Local Wi-Fi (mDNS)1.2ms Latency

Discovers the Mac's _localmetro._tcp service via Apple Bonjour & Android NsdManager. Zero configuration.

Tier 3: Mobile Hotspot Gateway2.5ms Latency

When phone provides hotspot to Mac, mDNS is blocked by Android AP isolation. LocalMetro uses UDP gateway beaconing to :47655 to bridge.

Tier 4: Remote Cloud RelayRoadmap Phase 3

End-to-end encrypted WebSocket tunnel when devices are on separate cellular connections.

Protocol Spec

{
  "v": 1,
  "id": "e4f8b1a2-3c4d-4e5f-a6b7-c8d9e0f1a2b3",
  "type": "clipboard",
  "sentAt": "2026-11-15T13:37:00Z",
  "payload": {
    "text": "https://github.com/0xdps/local-metro",
    "format": "text/plain",
    "sourceDevice": "Pixel-9-Pro"
  }
}

Contract checked via just protocol-check● 100% Type-Safe

Wire Framing Specification

Every transmission consists of a 4-byte big-endian unsigned integer indicating the length of the subsequent payload, followed immediately by UTF-8 encoded JSON.

// Header: 4 bytes BE length

uint32_be payload_length = htonl(json_bytes.len());

// Body: UTF-8 JSON up to 256 KB

write_all(&payload_length);

write_all(&json_bytes);

mDNS & Bonjour Discovery

On macOS, NWListener binds port 47655 and advertises service _localmetro._tcp. On Android, NsdManager queries for this service type.

// Service registration

Service: _localmetro._tcp.local

Port: 47655 (TCP)

TXT: deviceId=<uuid>, name=<hostname>

One-Time Cryptographic QR Pairing

When pairing for the first time, the Mac generates a cryptographically random token with a strict 2-minute expiration window. The QR code displays an URI:

lm://pair?v=1&id=9c2e-48a1&t=7f8b90a1c2d3&p=47655&h=MacBook-Pro.local

The Android device connects directly to the IP and port, passes the one-time token in a pair-request envelope. Once validated, both devices persist the trusted device ID into secure local storage. Subsequent sessions connect automatically without user intervention.