Integration

Local HTTP API

Every session stream port exposes a versioned HTTP surface on 127.0.0.1. It accepts the same command objects used by the CLI and MCP, so custom tools do not need to spawn a process for each action.

Discover the port

The stream server starts with the daemon. Query the active session to find its port:

bash

PORT=$(chrome-use --session demo stream status --json | jq -r '.data.port')
ORIGIN="http://127.0.0.1:$PORT"

Read endpoints

Endpoint	Result
`GET /api/v1/status`	Daemon engine and availability.
`GET /api/v1/tabs`	Last observed session tabs.
`GET /api/v1/sessions`	Locally discoverable sessions.

bash

curl -fsS "$ORIGIN/api/v1/status"
curl -fsS "$ORIGIN/api/v1/tabs"

Run a command

Post a daemon command object to /api/v1/command. The response is the normal chrome-use envelope.

bash

curl -fsS -X POST "$ORIGIN/api/v1/command" \
  -H "Origin: $ORIGIN" \
  -H 'Content-Type: application/json' \
  -d '{"id":"curl-1","action":"snapshot","interactive":true}'

Command fields match the JSON emitted by the corresponding CLI parser. Start with chrome-use <command> --help and the command reference when building an integration.

Security boundary

The server binds only to loopback. Versioned reads require a loopback Host and reject mismatched browser origins. Mutating command requests also require an Origin or Referer whose authority matches that Host. Requests without that match receive HTTP 403 and are never relayed to the daemon.

Error contract

CLI JSON, MCP structured content, and HTTP share the same failure fields:

Field	Meaning
`success`	`false` for a failed command.
`error`	Human-readable diagnostic.
`code`	Stable machine category such as `timeout` or `element_not_found`.
`retryable`	Whether retrying after a short recovery may succeed.

json

{"success":false,"error":"Timeout waiting for download","code":"timeout","retryable":true}