Skip to main content

Browser Extension

The ZenSearch browser extension brings your knowledge base into a Chrome side panel so your team can search, chat, and follow up without leaving the current page.

What it does​

  • Opens ZenSearch in the Chrome side panel
  • Supports signed-in user sessions as the primary auth path
  • Supports a publishable ZenSearch API key (zsk_pk_...) as an advanced fallback
  • Can optionally send the current page URL and selected text as page context
  • Persists conversation history locally in the browser extension
  • Supports keyboard launch with Ctrl+Shift+Z (Cmd+Shift+Z on macOS)

Download and install​

The extension is distributed through GitHub Releases as two zip archives:

  • zensearch-browser-extension-chrome.zip for direct user installation
  • zensearch-browser-extension-cws.zip for Chrome Web Store submission and formal packaging workflows
  • zensearch-browser-extension-store-metadata.json for Chrome Web Store listing fields

  1. Download the latest build from:

    https://zensearch.ai/downloads/browser-extension/chrome

  2. Extract the zip to a local folder.

  3. Open chrome://extensions in Chrome.

  4. Enable Developer mode.

  5. Click Load unpacked.

  6. Select the extracted extension folder.

Configure the extension​

The recommended setup is to sign in with your ZenSearch account from the extension settings.

  1. Open the extension options page.
  2. Leave Authentication mode set to Sign in with ZenSearch.
  3. Click Sign in to ZenSearch and complete the browser-based login flow.
  4. Select the active team if your account belongs to multiple teams.

Signed-in user sessions support ZenSearch deployments backed by OIDC or Clerk.

API key fallback mode​

For self-hosted or admin-managed deployments, you can still use API key mode.

Before using API key mode, create a dedicated publishable API key in ZenSearch:

  1. Open Settings → API Keys in the web app.
  2. Create a new key pair.
  3. Copy the publishable key (zsk_pk_...).
  4. Optionally restrict the key to the collections the extension should search.

Then configure the extension:

  1. Open the extension options page.
  2. Change Authentication mode to Use API key.
  3. Set API URL:
    • Cloud: https://api.zensearch.ai
    • Self-hosted: your own HTTPS API base URL
  4. Paste your publishable API key.
  5. Choose a theme (auto, light, or dark).
  6. Enable Include page context only if your team wants current-page signals.
  7. Click Save Settings.

Page context behavior​

When Include page context is enabled, the extension can send:

  • the current page URL without query strings or fragments
  • up to 1,000 characters of selected text from the active tab

This helps ZenSearch answer questions in the context of what the user is reading.

The extension does not send Chrome internal URLs such as chrome:// or extension URLs. Page context is disabled by default for privacy-first rollouts.

Security guidance​

  • Prefer signed-in user sessions for normal cloud and enterprise rollouts
  • Use publishable keys only in the browser extension when running API key mode
  • Do not use secret keys (zsk_sk_...) in the extension
  • Scope the key to the minimum required collections
  • Treat publishable keys as sensitive operational access even though they are designed for client-side use
  • Use self-hosted API URLs if your deployment requires private routing
  • Prefer HTTPS self-hosted API URLs for production rollouts

See API Keys for key management details.

Release flow​

The repository includes a dedicated GitHub Actions workflow for browser extension releases.

  • PRs that change apps/extension/** run build validation
  • Tags matching extension/v* build both extension zips and publish them to GitHub Releases

Chrome Web Store readiness​

The extension package is maintained so it is ready for Chrome Web Store submission:

  • manifest metadata is validated during release builds
  • the package includes the required 128x128 icon
  • homepage metadata points to the public extension landing page
  • a dedicated zensearch-browser-extension-cws.zip artifact is generated for store submission workflows

The repository also includes apps/extension/chrome-web-store.json with:

  • homepage URL
  • support URL
  • privacy policy URL
  • listing copy for the store submission flow
  • screenshot and promo asset guidance for the store listing

Use that metadata file together with the tagged zensearch-browser-extension-cws.zip artifact when preparing a Chrome Web Store submission.

Store listing assets​

Prepare Chrome Web Store assets from the real product UI rather than mock marketing art.

  • Capture at least two screenshots: the side panel on a live page and the extension options page
  • Prefer 1280x800 screenshots so they remain flexible for store upload requirements
  • Show page context, citations, or keyboard shortcut affordances in at least one screenshot
  • Remove private data, internal hostnames, and real customer content from every capture
  • If you create optional promo tiles, keep the composition centered on the Chrome side panel experience and ZenSearch branding

Troubleshooting​

The side panel opens but asks for setup​

Your API key has not been configured yet. Open the extension settings and paste a valid publishable key.

Page context does not work on some tabs​

Chrome may deny page scripting on protected pages or browser-internal URLs. The extension falls back to using the tab URL only when possible.

Self-hosted deployment does not connect​

Set the extension API URL to your self-hosted base URL and make sure the extension has permission to access that host.