@e9n/pi-webserver

Shared HTTP server for pi — one port, shared auth, and an event-bus mount system that other extensions plug into.

Features

• Single shared port — all extensions serve from one HTTP server (default 4100)
• Basic auth — protects page routes with HTTP Basic authentication
• API bearer token auth — separate full-access and read-only tokens for /api/* routes
• Cookie session auth — browser-friendly login page for API-token-only setups
• Prefix routing — longest-prefix match; prefix is stripped before calling the handler
• Event bus mounting — extensions mount via pi.events.emit("web:mount", ...) without importing
• Built-in dashboard — / lists all registered mounts with links
• Autostart — optionally start on session init via settings

Setup / Settings

Add to ~/.pi/agent/settings.json (project overrides in <project>/.pi/settings.json):

{
  "pi-webserver": {
    "autostart": true,
    "port": 4100,
    "auth": "mypassword",
    "apiToken": "my-secret-token",
    "apiReadToken": "my-read-token"
  }
}

| Key | Type | Default | Description | |-----|------|---------|-------------| | autostart | boolean | false | Start the server automatically on session start | | port | number | 4100 | HTTP port | | auth | string | null | null | Basic auth — "password" or "user:password" | | apiToken | string | null | null | Bearer token for full API access (all methods) | | apiReadToken | string | null | null | Bearer token for read-only API access (GET/HEAD) |

Commands

| Command | Description | |---------|-------------| | /web | Start on port 4100, or stop if already running | | /web <port> | Start on a specific port | | /web stop | Stop the server | | /web status | Show URL, auth status, and all mounts | | /web port [number] | Show or change the current port | | /web auth <password> | Enable Basic auth (username: pi) | | /web auth <user:pass> | Enable Basic auth with custom username | | /web auth off | Disable Basic auth | | /web api <token> | Set bearer token for full API access | | /web api read <token> | Set read-only bearer token (GET/HEAD only) | | /web api off | Disable API token auth | | /web api | Show API token status and mounted API routes |

Web UI

| Route | Description | |-------|-------------| | / | Dashboard listing all registered mounts | | /_api/mounts | JSON: all mounts (Basic auth) | | /_api/mounts/dashboard | JSON: non-API mounts (for nav shells) | | /_auth/login | Browser login page (when only API tokens are set) | | /_auth/logout | Clear session cookie | | /api/* | API routes — Bearer token auth (or open if no token set) |

For extension authors

Mount a page route via the event bus (no import needed):

export default function (pi: ExtensionAPI) {
  pi.events.on("web:ready", () => {
    pi.events.emit("web:mount", {
      name: "my-ext",
      label: "My Extension",
      description: "Does cool things",
      prefix: "/my-ext",
      handler: (req, res, subPath) => {
        res.writeHead(200, { "Content-Type": "text/html" });
        res.end("<h1>Hello</h1>");
      },
    });
  });
}

Mount an API route under /api/*:

pi.events.emit("web:mount-api", {
  name: "my-ext-api",
  label: "My Extension API",
  prefix: "/my-ext",           // mounts at /api/my-ext
  handler: (req, res, subPath) => { ... },
});

Events

| Event | Direction | Payload | |-------|-----------|---------| | web:ready | ← emitted by webserver on session start | {} | | web:mount | → webserver listens | MountConfig | | web:unmount | → webserver listens | { name: string } | | web:mount-api | → webserver listens | MountConfig | | web:unmount-api | → webserver listens | { name: string } |

Install

pi install npm:@e9n/pi-webserver

License

MIT