Browser Extension

The Cartographer browser extension (Chrome MV3) bridges your real browser and the Cartographer agent. Use it to record demonstrations, approve sensitive actions, and run flows in your authenticated Chrome profile when server-side browsers cannot complete MFA, payments, or SSO.

Dashboard: app.molar.it/dashboard/cartographer → Integrations → Extension

Product page: cartographer.molar.it

When to use the extension

Select browser adapter: extension when starting a run, or connect proactively with cartog browser connect.

Capabilities overview

Install the extension

Molar Cloud (recommended)

Install the unpacked extension from the Cartographer repository, or follow the install guide in the dashboard.

1. Open app.molar.it/dashboard/cartographer → Integrations → Extension.
2. Follow the install guide for enterprise policy deploy or local unpacked build.
3. Pin the extension and open the side panel on the target tab.

Local development (unpacked)

Build from the Cartographer self-host bundle (contact support@molar.it for access):

pnpm --filter @cartographer/extension install
pnpm --filter @cartographer/extension build

Load in Chrome:

1. Open chrome://extensions
2. Enable Developer mode
3. Load unpacked → select extension/dist/
4. Pin the extension

Verify:

pnpm --filter @cartographer/extension test
pnpm --filter @cartographer/extension typecheck

Record mode

Record mode captures demonstrations the planner can reuse on similar goals.

Start recording

1. Open the extension side panel on the target tab.
2. Grant explicit consent — recording does not start without user action.
3. Perform the flow (login, MFA, checkout, etc.).
4. Stop recording — chunks upload to the project Recordings library (/dashboard/projects/{id}/recordings).

What gets captured

Privacy controls

Recorded demos appear in the dashboard with skill hit rate — how often the planner cache matches this demo on new runs.

Replay: Open demo detail → Replay demo creates a new agent run. MCP: cartographer_replay_demo.

Relay sessions

The relay lets the agent worker drive your Chrome tab over a secured WebSocket. Relay connects your Chrome tab to the agent worker over a secured WebSocket.

  Agent worker                    Extension (your Chrome)
       │                                │
       │  WSS /v1/extension/relay       │
       │◄──────────────────────────────►│
       │  CDP-framed commands           │
       │  approvals + screenshots         │

Connect with cartog browser connect

cartog browser connect \
  --api-url https://api.cartographer.molar.it \
  --api-key "$CARTOGRAPHER_API_KEY" \
  --project-id <project-id> \
  --goal "Verify checkout with saved session"

Local development:

cartog browser connect \
  --api-url http://localhost:8000 \
  --api-key "$CARTOGRAPHER_API_KEY" \
  --project-id <project-id> \
  --goal "Verify checkout"

The CLI:

1. Requests a scoped relay token from POST /v1/extension/wss/token
2. Opens WebSocket to the relay (local default: wss://localhost:8443/v1/extension/relay)
3. Prints extension relay connected: <session_id>

Dry-run (print handshake frame without connecting):

cartog browser connect --dry-run --api-url http://localhost:8000 --project-id <id>

Relay security

Tokens are obtained from the API — never embed long-lived secrets in the extension.

Monitor connection status on Integrations → Extension: WSS status, JWT expiry countdown, reconnect instructions.

HITL approvals

Human-in-the-loop (HITL) pauses the agent when automation cannot safely proceed.

Actions that require approval

Approval flow

  Agent requests action
        │
        ▼
  DOM hash computed ──► Approval prompt (side panel + dashboard queue)
        │
        ├── Approve ──► Agent continues
        ├── Deny  ──► Run fails step
        └── Expire ──► Fail closed (stale DOM hash)

1. Agent enters pending_human — run detail shows HITL panel
2. Prompt appears in extension side panel and Integrations → Extension approval queue
3. You Approve or Deny — bound to current DOM hash
4. If the page changed since the request, approval fails closed (stale hash)
5. Resume after manual CAPTCHA/MFA if needed

Dashboard queue columns: type, URL, run id, timestamp, Approve/Deny buttons with real-time push over the extension relay WebSocket.

Take over

Take over opens the extension live view so you complete a step manually (CAPTCHA, MFA code entry), then Resume the run.

Kill switches

Every relay session can be aborted immediately:

Kill switch actions:

• Close WebSocket relay
• Detach Chrome debugger
• Clear pending approvals
• Clear DPoP session key
• Record kill reason in audit log

Integrations → Extension shows last kill-switch event timestamps (tab closed, sidepanel closed, global abort).

Run launch with extension adapter

From project hub → Start run:

Ensure:

1. Extension installed and side panel open on the target tab
2. Relay connected (cartog browser connect or dashboard-initiated session)
3. Target origin in project settings → Extension → origin allowlist

Dashboard integration

Enable record mode per project from Integrations → Extension; deep link opens the side panel on the active tab.

Security summary

For deployment hardening (TLS, token rotation, enterprise policy deploy), see Deployment.

Troubleshooting

More: Troubleshooting & FAQ.

Related