> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.chaser.sh/docs/guides/llms.txt.
> For full documentation content, see https://docs.chaser.sh/docs/guides/llms-full.txt.

# Browser Extensions

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

```bash
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:

```json
{
  "extension_id": "5b6f3b0f3c7a5f2c3e0f4c2d7e8a9b1c5d6e7f8091a2b3c4d5e6f7081920abcd",
  "path": "/data/chaser/extensions/5b6f3b0f3c7a5f2c3e0f4c2d7e8a9b1c5d6e7f8091a2b3c4d5e6f7081920abcd",
  "file_count": 14,
  "restarted": true
}
```

`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:

```bash
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:

```text
/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.

## Recommended workflow

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.

```bash
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.

## Related

- [Browser Sessions](/docs/sessions/browser-sessions)
- [Browser Automation](/docs/guides/browser-automation)
- [File Transfer](/docs/developer-tools/file-transfer)