Bridge Protocol

The bridge is a lightweight HTTP server embedded in the Tauri app during development. It enables tauri-agent-tools to evaluate JavaScript in the webview.

Endpoints

The bridge exposes eight HTTP endpoints:

Eval Endpoint

Request

POST http://127.0.0.1:{port}/eval

{
  "js": "document.title",
  "token": "a1b2c3d4e5f6...",
  "window": "main"
}

Response

Success (200):

{
  "result": "My Tauri App"
}

Authentication error (401/403):

Bridge authentication failed — check your token

Bad request (400):

Missing 'js' field

Communication Flow

sequenceDiagram
    participant CLI as tauri-agent-tools
    participant FS as /tmp/
    participant Bridge as Rust Bridge<br/>(tiny_http)
    participant WV as Tauri Webview

    Note over Bridge: App startup
    Bridge->>Bridge: Generate random token
    Bridge->>Bridge: Bind to 127.0.0.1:0 (random port)
    Bridge->>FS: Write tauri-dev-bridge-{pid}.token<br/>{port, token, pid}

    Note over CLI: Command execution
    CLI->>FS: Scan tauri-dev-bridge-*.token
    CLI->>CLI: Parse JSON, check PID liveness
    CLI->>CLI: Clean stale files from dead processes

    CLI->>Bridge: POST /eval {js, token}
    Bridge->>Bridge: Validate token
    Bridge->>Bridge: Generate UUID request ID
    Bridge->>WV: eval(wrapped JS with callback)
    WV->>WV: Evaluate expression
    WV->>Bridge: __TAURI_INTERNALS__.invoke("__dev_bridge_result", {id, value})
    Bridge->>Bridge: Match result by ID, unblock HTTP thread
    Bridge-->>CLI: {result: ...}

    Note over Bridge: App shutdown
    Bridge->>FS: Delete token file (scopeguard)

Token File Format

Token files are written to the system temp directory (/tmp/ on Linux/macOS):

Filename: tauri-dev-bridge-{pid}.token

Contents:

{
  "port": 54321,
  "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "pid": 12345
}

Authentication

• Every request must include the token field matching the generated token
• Token is a random 32-character alphanumeric string
• Mismatched tokens return HTTP 401/403

Security Properties

• Localhost only — bridge binds to 127.0.0.1, not 0.0.0.0
• Random port — no fixed port to target
• Token auth — prevents unauthorized access from other local processes
• Debug only — wrapped in cfg!(debug_assertions), compiled out of release builds
• Cleanup — token file deleted on exit via scopeguard
• Inspection is read-only — inspection commands only evaluate JS, never inject input events
• Interaction is debug-only — interaction commands use eval-based DOM dispatch, sandboxed to the webview

Log Capture Endpoint

Endpoint

POST http://127.0.0.1:{port}/logs

Request

{
  "token": "a1b2c3d4e5f6..."
}

The mode is selected by the presence of cursor: a bare { token } request keeps the legacy drain semantics byte-for-byte, so pre-v0.8 callers are unaffected.

Response

Success (200):

{
  "entries": [
    {
      "id": 41,
      "timestamp": 1710000000000,
      "level": "info",
      "target": "myapp::db",
      "message": "Connected to database",
      "source": "rust"
    },
    {
      "id": 42,
      "timestamp": 1710000001000,
      "level": "warn",
      "target": "stderr",
      "message": "deprecated flag used",
      "source": "sidecar:ffmpeg"
    }
  ],
  "cursor": 42,
  "dropped": 0
}

cursor and dropped are omitted in drain mode — their presence on the response is how clients feature-detect cursor support with zero extra round-trips.

Behavior

• Drain mode ({ token } only) drains the buffer — each entry is returned only once, and concurrent consumers steal entries from each other
• Cursor mode (v0.8+) is non-draining — each consumer tracks its own cursor, so any number of consumers can tail concurrently
• Cursor requests with waitMs > 0 long-poll on a worker thread (the bridge's accept loop is serial, so waiting inline would stall other endpoints)
• The buffer holds up to 1000 entries; oldest entries are dropped on overflow (visible as dropped in cursor mode)
• The buffer is populated by a tracing::Layer (Rust logs) and background reader threads (sidecar stdout/stderr)

Version Endpoint

Request

GET http://127.0.0.1:{port}/version

No authentication required.

Response

{
  "version": "0.8.0",
  "endpoints": ["/eval", "/logs", "/describe", "/version", "/process", "/capabilities", "/devtools", "/health"]
}

Describe Endpoint

Request

POST http://127.0.0.1:{port}/describe

{
  "token": "a1b2c3d4e5f6..."
}

Response

{
  "pid": 12345,
  "windows": ["main", "overlay", "settings"],
  "capabilities": ["eval", "logs", "describe"]
}

Error Handling