Guides

Browser Extensions

View as Markdown

Chaser browser sessions can load developer-supplied Chromium extensions using a dedicated browser extension upload flow.

This is intentionally narrower than sandbox file transfer:

  • Browser sessions do not expose generic upload/download endpoints.
  • Browser sessions do accept extension archives through a browser-specific multipart endpoint.
  • Extensions are stored on the browser workspace disk, so they follow the same persistence rules as browser profile state.

When to use this

Use browser extensions when your automation depends on:

  • wallet or auth helpers
  • content scripts for site-specific flows
  • custom background logic
  • browser UI or settings that are easiest to express as an extension

If you just need to automate pages through rebrowser-puppeteer-core, Puppeteer, or raw CDP, you do not need this flow.

Persistence model

Extension bundles are unpacked onto the browser disk under /data/chaser/extensions.

  • Ephemeral browser session: extensions disappear when the session is terminated.
  • Workspace-backed browser session: extensions persist and will be loaded again on later boots for the same workspace.

Because the browser shim also receives the same --seed and --user-data-dir for persistent browser workspaces, extension state and browser profile state stay aligned across restarts.

Upload an extension

Upload a .zip, .tar, or .tar.gz archive containing an unpacked Chromium extension directory.

Requirements:

  • manifest.json must exist at the root of the extension bundle
  • archives may include one top-level wrapper directory
  • symlinks are rejected
  • maximum bundle size is 16 MB per upload
  • only browser sessions support this endpoint

REST API

$curl -sS "$CHASER_API_URL/v1/sessions/<session_id>/browser/extensions" \
>  -H "Authorization: Bearer $CHASER_API_KEY" \
>  -F "bundle=@./my-extension.zip" \
>  -F "restart_browser=true" | jq

Example response:

1{
2  "extension_id": "5b6f3b0f3c7a5f2c3e0f4c2d7e8a9b1c5d6e7f8091a2b3c4d5e6f7081920abcd",
3  "path": "/data/chaser/extensions/5b6f3b0f3c7a5f2c3e0f4c2d7e8a9b1c5d6e7f8091a2b3c4d5e6f7081920abcd",
4  "file_count": 14,
5  "restarted": true
6}

restart_browser is optional and defaults to true. Set it to false when you want to stage multiple uploads first and restart only once.

Restart the browser

When restart_browser=false is used during upload, restart the browser explicitly to apply the new enabled extension set:

$curl -sS "$CHASER_API_URL/v1/sessions/<session_id>/browser/restart" \
>  -H "Authorization: Bearer $CHASER_API_KEY" \
>  -X POST | jq

The daemon waits for the browser to come back healthy before returning.

How loading works

Each uploaded bundle is content-addressed by SHA-256 and unpacked to its own directory.

Chaser keeps an enabled extension list at:

/data/chaser/extensions/enabled.list

On browser boot, the guest launcher passes the enabled extension directories through to the browser shim, which then launches Chromium with the matching extension configuration.

For reliable extension-heavy automation:

  1. Create a named browser workspace.
  2. Upload the required extension bundles once.
  3. Reuse that workspace for future browser sessions.
$chaser workspaces create --session-type browser --name extension-dev --json
$chaser browser --workspace extension-dev --json

That gives you durable cookies, local storage, and extension state together.

Notes

  • This feature is designed for developer-supplied bundles, not Chrome Web Store installation flows.
  • The current surface is optimized for unpacked Chromium-compatible extensions packaged as an archive for transport.
  • If your automation breaks after changing the enabled extension set, restart the browser session again before debugging CDP behavior.