Install

There are two real ways people end up using this project:

• install the published package in Pi
• work from the repo locally during development

The important thing is not to mix those up without meaning to, because Pi can end up loading a different copy than the one you think you are testing.

Install from npm in Pi

pi install npm:@demigodmode/pi-web-agent

That installs the published package.

For the published package, Pi loads the compiled runtime from dist/extension.js through the pi.extensions entry in package.json.

After install/reload, run:

/web-agent doctor

That checks whether the package loaded and reports the configured search, fetch, and headless backends.

Browser rendering

Headless rendering first tries a local Chromium-family browser. Supported local browsers are Chrome, Chromium, Edge, and Brave when they can be detected on Windows, macOS, or Linux.

If none is detected, web_explore falls back to Playwright-managed Chromium and still launches with headless: true. Firefox/Safari-only systems can still use search and plain HTTP reads; browser-rendered fallback uses Chromium.

Work from the repo locally

This repo also includes a project-local Pi extension entrypoint at .pi/extensions/pi-web-agent.ts.

That path is for local development and reloads while you are working in this repo.

Config files after install

The package stores presentation and backend settings in real JSON files.

Global config:

~/.pi/agent/extensions/pi-web-agent/config.json

Project config:

.pi/extensions/pi-web-agent/config.json

Project config overrides global config.

If you change settings through /web-agent, those files are what get updated.

Backend config

The default backend setup is:

{
  "backends": {
    "search": { "provider": "duckduckgo" },
    "fetch": { "provider": "http" },
    "headless": { "provider": "local-browser" }
  }
}

For a self-hosted setup, run SearXNG and Firecrawl yourself, then open:

/web-agent settings

Choose Backends to set:

• search provider: searxng
• SearXNG URL, for example http://localhost:8080
• fetch provider: firecrawl
• Firecrawl URL, for example http://localhost:3002
• optional fallback behavior

If your Firecrawl instance requires a key, prefer an environment variable:

PI_WEB_AGENT_FIRECRAWL_API_KEY=...

The settings UI does not write API keys. For local-only configs you can still add "apiKey": "..." to the fetch config manually.

Run /web-agent doctor after changing backend config. It validates required baseUrl values and checks configured SearXNG/Firecrawl endpoints with a short timeout.

Self-hosted backend config also supports explicit fallback and a small set of provider options. See Self-hosted backends for the full shape.

This package integrates with existing self-hosted services. SearXNG/Firecrawl installation, Docker Compose files, reverse proxies, TLS, and auth setup belong to those projects' docs.

Watch out for mixed setups

If you have both the npm-installed package and the local repo-based extension in play, it gets easy to think you are testing one copy when Pi is actually loading the other.

We already ran into exactly that during development.

If behavior looks stale, missing, or just weird, check what Pi actually loaded before you debug anything else.

How to sanity-check what Pi loaded

A few practical checks help:

• make a small visible local change and use /reload
• restart Pi after install changes
• check whether the behavior matches the local repo or the published package version
• if needed, temporarily remove one install path so there is only one source of truth

It is a boring problem, but it is the kind that wastes a lot of time if you miss it.