Installation & Quick Start
Deepaa ships as an npm CLI for macOS and Windows. No repository cloning required.
One-Prompt Install via Your Local Agent
Copy the prompt below and paste it into Claude Code, Codex, Cursor, or any local agent — it will install and launch Deepaa for you.
Install and start Deepaa (a local-first AI agent gateway & observability tool) on this machine: 1. Check the Node.js version — 22+ is required; if missing or outdated, install the LTS release first; 2. Run npm install -g deepaa for a global install; on a slow network, switch the npm registry to https://registry.npmmirror.com first; 3. Once installed, run deepaa to start the service — the browser opens http://localhost:3210 automatically (proxy on port 3211); 4. Verify the Web UI is reachable and report the URL back to me.
Install on macOS
Works on both Apple Silicon and Intel Macs.
1. Install Node.js (skip if installed)
brew install node
2. Install the Deepaa CLI
npm install -g deepaa
3. Start
deepaa
4. Register as a system service (optional: auto-start on login + crash recovery)
deepaa service install
Default ports: Web UI `http://localhost:3210`, proxy `http://localhost:3211`. Data directory `~/.deepaa`. A DeepAA shortcut appears in Applications automatically after install.
Install on Windows
Works on Windows 10/11 in PowerShell or Windows Terminal.
1. Install Node.js (skip if installed)
# Download LTS from https://nodejs.org # China mirror: https://npmmirror.com/mirrors/node/
2. Install the Deepaa CLI
npm install -g deepaa
3. Start
deepaa
4. Register as a system service (optional: auto-start on login + crash recovery)
deepaa service install
If PowerShell execution policy blocks global installs, run as administrator or use cmd. A DeepAA shortcut appears in the Start Menu automatically after install.
Faster Downloads in China
Users in China can dramatically speed up downloads via the npmmirror registry.
1. Configure the npm mirror (recommended, persists)
npm config set registry https://registry.npmmirror.com
2. Or specify it per install
npm install -g deepaa --registry=https://registry.npmmirror.com
3. Node.js installer mirror (CN)
https://npmmirror.com/mirrors/node/
If GitHub is slow, grab Node installers from the mirror; keep all npm dependencies on npmmirror.
Build from Source
For development and contributions. Requires Node.js 22+ and pnpm.
1. Clone repository
git clone https://github.com/AIAgentAndy/DeepAA
2. Install dependencies
cd DeepAA pnpm install
3. Build
pnpm build
4. Start
pnpm start
After building once, `pnpm start` launches production mode directly without rebuilding.
Agent Client Setup
Configure Claude Code or Codex to route traffic through the local proxy.
Claude Code
export ANTHROPIC_BASE_URL=http://localhost:3211/claude
Supports Anthropic Messages API compatible format.
Codex
export OPENAI_BASE_URL=http://localhost:3211/codex/v1
Supports OpenAI Chat Completions compatible format. Model IDs must be prefixed with the provider target, in the form `<targetId>_<modelId>`.
The proxy binds to `127.0.0.1` by default. For LAN access, explicitly set `HOST=0.0.0.0` and add your own access control.
Environment Variables
Runtime configuration options.
PORT=4000 PROXY_PORT=4001 node ./bin/deepaa.mjs
CLI Command Overview
Useful commands available right after installation:
# Smart start: starts whichever service is missing, opens the console when ready deepaa # Register as a system service (optional): auto-start on login + crash recovery deepaa service install # Show runtime and service registration status deepaa status # Stop the Web UI and proxy (registered services keep their registration) deepaa stop # Foreground run (development/debugging, Ctrl-C to stop) deepaa open # Show all commands deepaa help
Remote Model Pricing Catalog
The pricing catalog is published on this site and pulled automatically by clients:
https://deepaa.dev/data/defaults/llm_catalog.jsonl
It is JSONL: the first line holds catalog meta (schemaVersion / catalogRevision / publishedAt / FX rates / holiday calendars), followed by one provider object per line with model-level pricing. `#` and `//` comment lines and blank lines are skipped by consumers.
Data Storage
Captured data (including API keys, prompts, responses) is stored in the `~/.deepaa` directory, containing:
- data/captures/v2/capture-*.jsonl — Raw JSONL capture files
- data/blobs/<sha256>.body.gz — Large response body blob storage
- data/deepaa.sqlite — Indexes and aggregated views
- data/proxy-config.json — Local proxy configuration