Skip to content

Expose the bridge through a tunnel

Security · API

The bridge remains bound to 127.0.0.1. A tunnel provides the HTTPS edge; the bridge still authenticates every application request.

A hosted application cannot reach a developer's bridge through its own 127.0.0.1: that address refers to the application server. A deliberately configured tunnel or private gateway is required. The bridge has no automatic discovery, device pairing, OAuth server or authenticated outbound relay.

Configure the gateway hostname

For a public hostname such as bridge.example.com, stop the service and add the exact values to config.json:

{
  "allowedHosts": ["localhost", "127.0.0.1", "bridge.example.com"],
  "allowedOrigins": ["https://bridge.example.com"]
}

Merge these settings into the existing file; do not replace the whole configuration. Restart the service.

Create a separate scoped client token under Diagnostics → Application access. Keep the owner token local.

Cloudflare Tunnel

A named tunnel can route bridge.example.com to http://127.0.0.1:8766. For a short-lived test:

cloudflared tunnel --url http://127.0.0.1:8766

Add the actual assigned hostname and HTTPS origin to the bridge allowlists before using it. Follow Cloudflare's local tunnel documentation for current setup requirements. Access policies can provide an additional edge check; they do not replace bridge authentication.

ngrok

ngrok http http://127.0.0.1:8766

Configure the assigned hostname and HTTPS origin in the allowlists. See ngrok's HTTP endpoint documentation.

Streaming and verification

Use https://bridge.example.com/v1 as the SDK base URL and the same scoped bridge token as api_key. Preserve Authorization, Idempotency-Key, Last-Event-ID, X-Bridge-Image-Revision, and the response header X-Bridge-Job-Id. Disable proxy response buffering. Completion streams send five-second keepalives; orchestration streams send 15-second heartbeats. A nonstreaming completion needs a proxy request timeout longer than the configured completion deadline.

curl --fail-with-body "https://bridge.example.com/v1/bridge/status" \
  -H "Authorization: Bearer $BRIDGE_TOKEN"

curl -N "https://bridge.example.com/v1/bridge/events" \
  -H "Authorization: Bearer $BRIDGE_TOKEN"

Check that a connection without a token returns 401 and an unconfigured Host or Origin returns 403. Events should arrive incrementally while the connection is open.

Do not put tokens in URLs. A remote token with an execution-capable profile can cause local actions with the OS user's privileges; provision it only for a trusted application.