Synaptic Playwright Sidecar

In-repo browser sidecar used by Synaptic's Elixir planner (browser_task).

Why this exists

• Synaptic (Elixir) is the planner/brain.
• This sidecar executes primitive browser actions only.
• Contract:
  • POST /session/start
  • POST /action
  • POST /session/close

Install and run

From the repository root:

cd sidecar/playwright
npm install
npm run start

By default the server listens on 127.0.0.1:3456.

Environment variables

• PORT (default 3456)
• HOST (default 127.0.0.1)
• BROWSER_TYPE (chromium, firefox, webkit; default chromium)
• BROWSER_HEADLESS (true/false; default true)
• BROWSER_HUMAN_EMULATION (true/false; default true)
• BROWSER_CHANNEL (default none; in human emulation on Chromium defaults to chrome)
• BROWSER_USER_AGENT (optional default UA used in human emulation)
• BROWSER_LOCALE (optional default locale used in human emulation)
• BROWSER_TIMEZONE_ID (optional default timezone used in human emulation)
• BROWSER_COLOR_SCHEME (optional default color scheme, e.g. light or dark)
• DEFAULT_ACTION_TIMEOUT_MS (default 30000)

API examples

POST /session/start

Request:

{
  "session_id": "optional-session-id",
  "session_options": {
    "headless": false,
    "viewport": { "width": 1400, "height": 900 },
    "human_emulation": true,
    "user_agent": "optional custom UA",
    "locale": "pl-PL",
    "timezone_id": "Europe/Warsaw",
    "color_scheme": "light",
    "channel": "chrome",
    "storage_state_path": "/absolute/or/relative/path/to/storage-state.json"
  }
}

Response:

{
  "session_id": "optional-session-id",
  "browser_type": "chromium",
  "headless": false,
  "session_options": {
    "headless": false,
    "viewport": { "width": 1400, "height": 900 },
    "human_emulation": true,
    "user_agent": null,
    "locale": null,
    "timezone_id": null,
    "color_scheme": null,
    "channel": null,
    "storage_state_path": "/absolute/or/relative/path/to/storage-state.json"
  },
  "created_at": "2026-02-21T00:00:00.000Z"
}

When session_options.storage_state_path is set:

• /session/start loads existing storage state from that path (if file exists).
• /session/close writes current context storage state to that path.

POST /action

Request:

{
  "session_id": "optional-session-id",
  "action": "navigate",
  "params": {
    "url": "https://example.com"
  },
  "timeout_ms": 15000
}

Success response:

{
  "ok": true,
  "action": "navigate",
  "result": {
    "url": "https://example.com/"
  }
}

Failure response:

{
  "ok": false,
  "action": "navigate",
  "error": {
    "code": "action_timeout",
    "message": "Timeout 15000ms exceeded.",
    "retryable": true
  }
}

POST /session/close

Request:

{
  "session_id": "optional-session-id"
}

Response:

{
  "ok": true,
  "session_id": "optional-session-id"
}

Supported action enum (v1)

• navigate
• click
• type
• select
• wait_for
• extract_text
• extract_json
• screenshot
• get_url
• get_title
• press
• scroll