Broski Bridge

The bridge server connects your phone to AI coding agents running on your computer.

What is the Bridge?

The Broski Bridge is a lightweight server that runs on your desktop (Mac, Linux, or Windows) and acts as the communication hub between your phone and the AI coding agent. It serves two critical purposes:

Protocol Translation - Converts WebSocket messages from your phone into API calls to the AI backend
Network Bridging - Makes your local AI agent accessible from anywhere via multiple connection methods

Installation

bash

broski

Verify your setup

Run broski doctor to check that everything is configured correctly.

Commands

bash

broski                 # Start server (default)
broski install         # Install as background service
broski uninstall       # Remove background service
broski status          # Check if bridge is running
broski stop            # Stop background service
broski qr              # Show QR code to pair phone
broski doctor          # Full diagnostics
broski doctor --fix    # Apply safe fixes
broski logs --export   # Export diagnostics bundle
broski setup-tailscale # Set up Tailscale for remote access

Architecture

Your Phone

Chat UI

Projects

File Browser

Your Desktop

Bridge ServerPort 18274

↓

AI BackendOpenCode / Claude

↓

Your Code (Filesystem)

↓

AI Cloud (Anthropic/OpenAI)

Connection Types: Local WiFi (ws://) • Tailscale VPN (ws://) • Tailscale Funnel (wss://)

Component Responsibilities

Component	Responsibility
Phone App	User interface, WebSocket client, state management, caching
Bridge Server	WebSocket server, message routing, event batching, health monitoring
AI Backend	Session management, AI reasoning, tool execution, file operations
Filesystem	Your actual code files that the AI reads and modifies

Data Flow

When you send a message from your phone:

Phone App: User types "Fix the bug in auth.ts"

↓

WebSocket: type: "chat", sessionId, content

↓

Bridge Server: Receives message, calls AI backend API

↓

AI Backend: Processes request, executes tools (Read, Edit, Bash)

↓

Bridge Server: Receives events, batches and forwards to phone

↓

Phone App: Displays streaming response, tool calls, and results

Connection Types

Broski supports multiple connection methods for different scenarios:

Type	Latency	Security	Setup	Use Case
Local WiFi	1-30ms	Local network only	Automatic	Home/office, fastest
Tailscale VPN	30-100ms	WireGuard encrypted	Install app on both	Remote, secure
Tailscale Funnel	Variable	TLS 1.3 (HTTPS)	Enable in admin console	Public access, no VPN on phone

How It Works

Bridge starts

WebSocket server runs on your system with a QR code containing connection info

Phone scans QR

Broski app extracts host, port, and auth token from the QR code payload

Connection established

Phone connects via WebSocket (local WiFi, Tailscale, or Funnel)

Messages relay

Your messages go to AI agent, responses and tool calls stream back in real-time

Supported AI Agents

Claude CodeOfficial Anthropic CLI

OpenCodeMulti-provider agent

CodexOpenAI models

Version Requirements

Component	Minimum Version	Recommended
OpenCode	Latest	Latest
Claude Code CLI	Latest	Latest
macOS	12 (Monterey)	14+ (Sonoma)
Windows	10 (1903+)	11
Linux	Ubuntu 20.04+	Ubuntu 22.04+

Security

Privacy by Design

All traffic stays on your local network or encrypted Tailscale tunnel. No data is sent to Broski servers. Connection is secured with a cryptographically random token stored locally on your machine.

Security Feature	Implementation
Auth Token	24 bytes (192 bits) cryptographically random, base64url encoded
Token Validation	Timing-safe comparison to prevent timing attacks
Token Storage	~/.broski/token.json with 0600 permissions (owner read/write only)
Local WiFi	Unencrypted but local-only (trusted network)
Tailscale	WireGuard encryption (military-grade)
Funnel	TLS 1.3 HTTPS (public but encrypted)

Next Steps

Configuration

CLI options, environment variables, and config files

Remote Access

Set up Tailscale for access from anywhere

Background Service

Run bridge automatically on boot