Local Bridge

An ultra-fast, secure local gateway that connects the browser-based Pieeg Cloud to services on your own network. It receives a real-time data stream from a browser via WebRTC P2P data channel and forwards it locally over protocols such as OSC — with minimal latency and near-zero setup.

Why it exists

Pieeg Cloud runs entirely in the browser and has no backend of its own. To reach local software (VRChat, TouchDesigner, Max/MSP, Ableton via OSC, game engines, etc.), it establishes a WebRTC peer-to-peer data channel with the Local Bridge running on your machine. Data flows directly between browser and bridge via loopback or LAN — nothing is relayed through the cloud. The bridge turns the incoming JSON stream into real OSC packets on 127.0.0.1 (or any host on your LAN).

Features

• Single standalone binary — ~5 MB, no runtime, no dependencies to install
• Instant startup, low memory — pure Rust / Tokio
• System tray — runs quietly in background; right-click to show UI, regenerate code, or quit
• Direct P2P connection — WebRTC data channel; all data stays local (loopback/LAN)
• Reversed pairing flow — bridge requests a session from the cloud and gets back a 6-character share code; you enter it in Pieeg Cloud
• Encrypted transport — DTLS for the P2P data channel; signaling uses HTTPS
• STUN/TURN aware — ICE servers provided by the cloud session for reliable NAT traversal
• Automatic discovery — finds local OSC apps via mDNS (_osc._udp)
• Protocol-agnostic core — pluggable adapters; OSC ships first
• Cross-platform — Windows, macOS, Linux

Installation

Quick Start — Download & Run (1 minute)

Windows

1. Download for Windows (opens in a new tab) — get pieeg-local-bridge-x86_64-pc-windows-msvc.zip
2. Extract the ZIP file anywhere
3. Double-click pieeg-local-bridge.exe
4. ✅ Done! Look for the tray icon (bottom-right, near clock)
5. Right-click the tray icon → Show Control UI to see your pairing code

macOS

# Choose your Mac type:
 
# Apple Silicon (M1/M2/M3/M4) — Most modern Macs
curl -L https://github.com/pieeg-club/PiEEG-local-bridge/releases/latest/download/pieeg-local-bridge-aarch64-apple-darwin.tar.gz | tar xz
cd pieeg-local-bridge-aarch64-apple-darwin && ./pieeg-local-bridge
 
# Intel Macs — 2020 and earlier
curl -L https://github.com/pieeg-club/PiEEG-local-bridge/releases/latest/download/pieeg-local-bridge-x86_64-apple-darwin.tar.gz | tar xz
cd pieeg-local-bridge-x86_64-apple-darwin && ./pieeg-local-bridge

Linux

# Download and run (x86_64)
curl -L https://github.com/pieeg-club/PiEEG-local-bridge/releases/latest/download/pieeg-local-bridge-x86_64-unknown-linux-gnu.tar.gz | tar xz
cd pieeg-local-bridge-x86_64-unknown-linux-gnu && ./pieeg-local-bridge

What happens next:

• ✅ Control UI opens automatically: http://127.0.0.1:47800
• ✅ 6-character share code displayed (e.g. KHSP3W)
• ✅ System tray icon appears — right-click for menu

Build from Source (Optional)

Only needed if you want to modify the code or target an unsupported platform.

git clone https://github.com/pieeg-club/PiEEG-local-bridge.git
cd PiEEG-local-bridge
cargo build --release
./target/release/pieeg-local-bridge

Requirements: Rust (opens in a new tab) 1.70+

How to Use

Pairing with Pieeg Cloud

1. Run the Local Bridge. On startup it contacts the cloud signaling server and displays a 6-character share code (e.g. KHSP3W) at http://127.0.0.1:47800.

2. In Pieeg Cloud, click Connect to Local Bridge and enter the share code.

3. The browser and bridge perform a one-time WebRTC handshake (SDP/ICE exchange via the cloud signaling server).

4. A direct P2P data channel opens between browser and bridge. All data flows locally (loopback or LAN) — nothing is relayed through the cloud.

5. Incoming data frames are mapped to OSC and sent to your chosen destination.

The whole setup takes under a minute and requires no technical knowledge.

Data Mapping

The router applies two ordered, generic rules — no producer field names are hardcoded:

1. Explicit Envelope

Any frame containing an osc field is forwarded verbatim, giving producers precise control:

{ "osc": { "address": "/avatar/parameters/EEG_Alpha", "args": [0.42] } }
{ "osc": [ 
    { "address": "/a", "args": [1] }, 
    { "address": "/b", "args": [true] } 
  ] 
}

2. Generic Flatten

Any other JSON object is walked recursively; every number/bool/string leaf becomes an OSC address built from its JSON path. Transport metadata keys (type, t, ts, etc.) are skipped.

Example:

{ "channels": [0.1, 0.2, 0.3], "t": 123 }

Becomes:

/pieeg/channels/0  0.1
/pieeg/channels/1  0.2
/pieeg/channels/2  0.3

Configuration

Settings are persisted as JSON and edited from the UI (no manual editing needed):

CLI Options

Architecture

The bridge is deliberately vendor- and protocol-neutral:

Browser (WebRTC P2P) ──► router (generic mapping) ──► adapters (OSC, …)

Adding a new output protocol means adding one adapter — nothing else changes.

Security

• P2P data channel encrypted with DTLS — WebRTC data flows directly between browser and bridge (loopback/LAN), not through the cloud
• One-time signaling handshake — SDP/ICE exchange uses HTTPS; only occurs at connection setup
• Share code as secret — the 6-character code is the trust anchor; regenerate to mint a new cloud session and revoke access
• CORS agnostic — no vendor origins baked in; configure allowed origins via --allow-origin or JSON config
• Local-only control API — listens only on 127.0.0.1
• No cloud relay for data — after handshake, all data stays local

System Tray

The bridge runs quietly in your system tray (Windows notification area). Right-click the tray icon for:

• Show Control UI — opens http://127.0.0.1:47800 in your browser
• Regenerate Pairing Code — creates a new cloud session (new 6-character code) and disconnects any active session
• Quit — stops the bridge cleanly

Troubleshooting

Bridge won't start

• Check if port 47800 is already in use: netstat -an | findstr 47800 (Windows) or lsof -i :47800 (macOS/Linux)
• Try a different port: pieeg-local-bridge --port 47801

Can't connect from Pieeg Cloud

• Verify the share code is correct (it's case-sensitive)
• Check if your firewall is blocking the connection
• Try regenerating the pairing code from the system tray menu

No OSC output

• Use the mDNS discovery feature in the UI to find local OSC apps
• Verify your OSC application is listening on the configured port
• Check the data mapping rules (enable/disable flattening as needed)

macOS "unidentified developer" warning

• Right-click the app → Open, then click Open in the dialog
• Or: System Settings → Privacy & Security → allow the app

Source Code

The Local Bridge is open source (MIT license):

• GitHub: pieeg-club/PiEEG-local-bridge (opens in a new tab)
• Language: Rust
• Size: ~5 MB standalone binary
• Dependencies: None (pure Rust + Tokio)