@maintainer-pro/ai-server

Local Node chat server (sidecar) for Maintainer Pro. Start it with npx — no custom server.mjs.

It uses @maintainer-pro/ai-cli to talk to Cursor (agent), Claude (claude), or Antigravity (agy).

This process is not the host product backend. Run it beside the app in development. The sandbox setup guide uses port 3100 so it does not collide with the host (:3000 / :5173). The binary default with no env is port 3000.

It is not what you ship as the production website. Without this process, localhost:3100 is down and a page that loads the widget from there will show no chat. Production should serve ai-ui.iife.js as a static file and call a real chat API — see @maintainer-pro/ai-ui.

Quick start

npx --yes --prefer-online @maintainer-pro/ai-server@latest

Put a .env in the current directory (from the admin setup guide or by hand). CLI flags override env.

Requires Node.js 22+ and one authenticated coding-agent CLI. npx also installs @maintainer-pro/ai-ui so GET /ai-ui.iife.js is available.

Routes

| Path | Purpose | |------|---------| | GET / POST /api/chat | Chat (agent + Maintainer Pro store) | | WS /api/ws (also /ws) | Live AI events (subscribe, chat.run, message.created) | | GET /embed-config.js | window.__MAINTAINER_PRO__ — aiServerUrl, apiUrl, aiServerWsUrl, client keys | | GET /ai-ui.iife.js | Embed widget from @maintainer-pro/ai-ui (unless a file exists in AI_SERVER_UI) | | other paths | Static files from AI_SERVER_UI |

A copied ai-ui.iife.js in the UI folder is served first and will not update when you npm update @maintainer-pro/ai-ui. Prefer the node_modules copy, then restart this process.

Config

| Env / flag | Purpose | |------------|---------| | PORT / --port | Listen port (binary default 3000; setup guide uses 3100) | | AI_CLI_WORKSPACE / --workspace | Folder the agent may edit | | AI_SERVER_UI / --ui | Static UI folder | | CORS_ORIGIN / --cors-origin | Browser origin of the host app | | --env-file | Env file path (default ./.env) | | MAINTAINER_PRO_URL | Admin base URL | | MAINTAINER_PRO_API_KEY | Server API key | | MAINTAINER_PRO_CLIENT_API_KEY | Client key (served at /embed-config.js) | | AI_SERVER_URL | Public chat origin (e.g. http://localhost:3100). Included in /embed-config.js as aiServerUrl / apiUrl. If unset, derived from the request Host. | | AI_CLI_PROVIDER | auto | claude | cursor | antigravity | | AI_SERVER_PRODUCT_DESCRIPTION | Optional product text for the agent prompt |

npx --yes --prefer-online @maintainer-pro/ai-server@latest --port 3100 --ui . --workspace .

Related packages

| Package | Role | |---------|------| | @maintainer-pro/ai-cli | Talks to coding agents | | @maintainer-pro/ai-ui | Embed widget (/ai-ui.iife.js) |