Hyperbeam Bridge

The hyperbeam-bridge manages remote, embeddable Chromium browsers via the Hyperbeam API. This allows both the AI Agent and the User to interact with external websites (like brand stores) within a secure, session-scoped iframe.

Session Architecture

sequenceDiagram
    participant O as Orchestrator
    participant HB as Hyperbeam Bridge
    participant API as Hyperbeam Cloud API
    participant EXT as Chrome Extension
    participant C as Client

    O->>HB: POST /sessions (create)
    HB->>API: Spin up cloud Chromium
    API-->>HB: embedUrl + session handle
    HB-->>O: SessionView with embedUrl

    C->>C: Embed iframe (embedUrl)
    EXT->>HB: POST /hyperbeam/events (DOM_SNAPSHOT)
    EXT->>HB: POST /hyperbeam/events (ELEMENTS_INDEXED)

    O->>HB: GET /elements (query indexed DOM)
    O->>HB: POST /agent-action (CLICK element)
    HB-->>O: Updated SessionView
    HB->>O: POST /internal/hyperbeam/events (bridge event)

Endpoints

Session Management

Method	Path	Description
`POST`	`/api/v1/households/{id}/hyperbeam/sessions`	Create a new browser session
`GET`	`/api/v1/households/{id}/hyperbeam/sessions`	List all sessions
`GET`	`/api/v1/households/{id}/hyperbeam/sessions/{sId}`	Get session state + embed URL
`POST`	`/api/v1/households/{id}/hyperbeam/sessions/{sId}/terminate`	Forcefully shut down session

Create Session:

{
  "startUrl": "https://example-retailer.com/item/123",
  "missionId": "msn_xxx",
  "role": "CONTROLLER",
  "extensionRequired": true
}

Takeover Control

Because both the AI Agent and the User can interact with the same browser, a "takeover" lock prevents conflicts:

Method	Path	Description
`POST`	`/api/v1/households/{id}/hyperbeam/sessions/{sId}/takeover`	User takes control (agent blocked)
`POST`	`/api/v1/households/{id}/hyperbeam/sessions/{sId}/release`	User releases control (agent resumes)

Agent Actions

The agent interacts with the browser through structured DOM actions, not raw pixels:

Method	Path	Description
`POST`	`/api/v1/households/{id}/hyperbeam/sessions/{sId}/agent-action`	Execute a DOM action
`GET`	`/api/v1/households/{id}/hyperbeam/sessions/{sId}/elements`	Query indexed elements (params: `query`, `role`, `limit`)

Agent Action Types:

Action	Description
`CLICK`	Click an indexed element by `elementId`
`TYPE`	Type `text` into an element
`SCROLL`	Scroll the page
`NAVIGATE`	Navigate to a `url`
`QUERY_ELEMENTS`	Re-query the DOM for interactive elements
`SNAPSHOT`	Capture a DOM snapshot

Extension Events

A Chrome Extension running inside the Hyperbeam instance reports DOM state:

Method	Path	Description
`POST`	`/api/v1/hyperbeam/events`	Receive signed extension events

Extension Event Types:

Event	Description
`DOM_SNAPSHOT`	Full page DOM captured
`ELEMENTS_INDEXED`	Interactive elements indexed and ready for agent queries
`ACTION_RESULT`	Result of an executed agent action
`PAGE_CONTEXT_CHANGED`	Page navigation or significant DOM mutation

Session Lifecycle

See Data Models → Hyperbeam Session Lifecycle for the state diagram.

Configuration

Variable	Default	Description
`PERSISTENCE_BACKEND`	`inmemory`	`firestore` or `inmemory`
`HYPERBEAM_ENFORCE_EVENT_SIGNATURES`	`false`	Verify HMAC signatures on extension events
`HYPERBEAM_EVENT_SIGNING_SECRET`	`dev-event-secret-change-me`	HMAC secret for event verification
`ORCHESTRATOR_BASE_URL`	`http://orchestrator:8003/api/v1`	Orchestrator URL for bridge events
`ORCHESTRATOR_EVENTS_ENABLED`	`true`	Forward events to Orchestrator
`ORCHESTRATOR_EVENTS_REQUIRED`	`false`	Fail if Orchestrator is unreachable
`ORCHESTRATOR_INTERNAL_TOKEN`	`dev-internal-token`	Token for internal Orchestrator calls
`ARTIFACTS_AUDIT_BASE_URL`	`http://artifacts-audit:8007/api/v1`	Audit service URL
`ARTIFACTS_AUDIT_ENABLED`	`true`	Enable recording persistence

Hyperbeam Bridge

On this page