FleetQ Bridge — Local Compute Gateway

FleetQ Bridge is a lightweight Go binary that runs on your local machine (macOS or Linux) and connects it to the FleetQ cloud platform over a secure WebSocket. Once connected, FleetQ can route experiments, projects, and agent requests to your machine — running local LLMs and AI agents at zero cloud cost.

How it works

Bridge establishes a persistent WebSocket connection to FleetQ's relay infrastructure. When FleetQ needs to run a task on your machine, it sends a request through the WebSocket, Bridge routes it to the appropriate local backend, and streams the response back.

FleetQ Cloud                    Relay (WSS)                    Your Machine
    │                              │                               │
    │   Experiment runs            │                               │
    │   "Use claude-code agent"    │                               │
    │─────────────────────────────>│   WebSocket message           │
    │                              │   (agent.request)             │
    │                              │──────────────────────────────>│  Bridge daemon
    │                              │                               │     │
    │                              │                               │     ├─ Claude Code
    │                              │                               │     ├─ Codex
    │                              │                               │     ├─ Ollama (LLMs)
    │                              │                               │     ├─ LM Studio
    │                              │                               │     └─ MCP servers
    │                              │                               │
    │                              │   WebSocket chunks            │
    │                              │   (client-relay.chunk)        │
    │   Streaming response         │<──────────────────────────────│
    │<─────────────────────────────│                               │
    │                              │                               │

The relay uses the Pusher/Reverb protocol over TLS (WSS). Each team gets a private channel (private-daemon.{'{'}teamId{'}'}) that only authenticated bridges can subscribe to.

Installation

One-line install on macOS and Linux:

curl -fsSL https://get.fleetq.net | sh

Or download directly from the platform:

curl -fsSL https://fleetq.net/get/bridge | sh

The script auto-detects your OS and architecture (macOS arm64/x86_64, Linux x64/arm64) and installs the fleetq-bridge binary to /usr/local/bin or ~/.local/bin.

Authenticating

First, create an API token in Team Settings → API Tokens, then log in:

fleetq-bridge login --api-url https://fleetq.net --api-key YOUR_API_TOKEN

This saves your credentials to ~/.fleetq/bridge.json. You only need to do this once per machine.

Starting the bridge

fleetq-bridge start

On startup, Bridge:

1. Discovers local LLM endpoints (Ollama, LM Studio) and CLI agents (Claude Code, Codex, Gemini)
2. Registers with FleetQ via REST API — receives WebSocket credentials
3. Connects to the relay via WSS and subscribes to the team's private channel
4. Sends heartbeats every 30 seconds to keep the connection alive
5. Refreshes endpoints every 60 seconds (detects new models, agents coming online/offline)

Optional flags

fleetq-bridge start --ollama http://gpu-server:11434 --lmstudio http://localhost:1234

Agent discovery

Bridge probes for locally installed CLI agents by checking if their binaries are in $PATH:

Agents are marked found: true/false in the endpoints manifest. Only found agents are available for routing. While Bridge itself costs nothing, agents that call external APIs (Anthropic, OpenAI, Google) require their own API keys set on the machine where Bridge runs.

LLM endpoints

Bridge discovers and proxies requests to local LLM servers:

Bridge probes each configured endpoint on startup and every 60 seconds. Available models are reported to FleetQ and appear in the platform's model selector. Streaming responses are chunked back through the WebSocket in real-time.

MCP server proxying

Bridge can manage local MCP servers (Playwright, filesystem, custom tools) and proxy tool calls from the FleetQ platform to them. This means FleetQ experiments can use tools running on your machine.

Configuration

Create ~/.fleetq/mcp.json with your MCP server definitions:

{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-playwright"],
      "env": {}
    },
    "filesystem": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-filesystem", "/home/user/projects"],
      "env": {}
    }
  }
}

On startup, Bridge spawns each MCP server as a child process, performs the JSON-RPC 2.0 handshake (initialize + notifications/initialized), and keeps them running for the lifetime of the bridge session. Server names are reported to FleetQ and appear in the Bridge tab.

How proxy calls work

1. FleetQ sends POST /api/v1/bridge/mcp-call with server name, method, and params
2. The request is pushed to Redis and forwarded to Bridge via WebSocket
3. Bridge dispatches the JSON-RPC call to the local MCP server's stdin
4. The MCP server responds on stdout; Bridge sends the result back through the WebSocket
5. FleetQ receives the result and continues the experiment/workflow

Recommended MCP servers

These MCP servers work well with FleetQ Bridge for common automation tasks:

After installing, add the server to your ~/.fleetq/mcp.json and restart Bridge. The server will appear in your Bridge connection's MCP server list.

Multi-bridge support

A team can have multiple active Bridge connections simultaneously — for example, a developer's laptop and a GPU server. FleetQ's BridgeRouter picks the best bridge for each request based on the routing mode:

Configure routing mode via MCP tools (bridge_set_routing) or the Bridge tab in Settings. You can also label bridges (bridge_rename) for easier identification.

Running as a service

For always-on connectivity, run Bridge as a system service that starts on boot and auto-restarts on failure.

macOS (launchd)

Create ~/Library/LaunchAgents/com.fleetq.bridge.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.fleetq.bridge</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/fleetq-bridge</string>
        <string>start</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/fleetq-bridge.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/fleetq-bridge.log</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.fleetq.bridge.plist

Linux (systemd)

Create ~/.config/systemd/user/fleetq-bridge.service:

[Unit]
Description=FleetQ Bridge Daemon
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/fleetq-bridge start
Restart=always
RestartSec=5
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target

systemctl --user enable --now fleetq-bridge

Bridge MCP tools

FleetQ's MCP server includes tools for managing bridge connections programmatically:

REST API endpoints

Bridge-related REST API endpoints (all require Sanctum bearer token):

Troubleshooting

Security

• TLS everywhere: Bridge connects over WSS (TLS-encrypted WebSocket). API calls use HTTPS.
• Token auth: Bridge authenticates with your Sanctum API token. Tokens are team-scoped.
• Channel isolation: Each team gets a private Reverb channel. Subscription requires HMAC-SHA256 authentication.
• No inbound ports: Bridge only makes outbound connections. Nothing is exposed on your local network.
• MCP sandboxing: Only configured MCP servers can be called. No arbitrary command execution.
• Graceful shutdown: Bridge notifies FleetQ on disconnect (Ctrl+C, SIGTERM) so the connection is cleaned up immediately.

Configuration reference