System requirements
- Node.js 18+ (22 recommended)
- macOS, Linux, or Windows (WSL2 recommended)
Run npx polpo-ai to start — the setup wizard configures your model and API keys automatically.
npx (recommended)
npm / pnpm
Docker
From Source
No install needed. Polpo starts the server and dashboard on http://localhost:3000. If no config exists, it opens the setup wizard automatically. npm install -g @polpo-ai/polpo
pnpm add -g @polpo-ai/polpo
polpo launches the TUI where you can start chatting with Polpo. Use polpo serve for the web dashboard.docker run -d \
--name polpo \
-p 3000:3000 \
-v $(pwd):/workspace \
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
ghcr.io/lumea-labs/polpo:latest
Docker Compose
services:
polpo:
image: ghcr.io/lumea-labs/polpo:latest
ports:
- "3000:3000"
volumes:
- ./workspace:/workspace
environment:
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
- OPENAI_API_KEY=${OPENAI_API_KEY:-}
restart: unless-stopped
Volumes & ports
| Mount | Purpose |
|---|
/workspace | Project directory. Must be persistent — contains all state, plans, and agent files. |
| Port | Description |
|---|
3000 | OpenAI-compatible chat (/v1/chat/completions), REST API, SSE, WebSocket |
Health check
curl http://localhost:3000/api/v1/health
The /workspace volume contains all state. Use a named volume or bind mount to avoid data loss.
Requires pnpm 10+.git clone https://github.com/lumea-labs/polpo.git
cd polpo
pnpm install
pnpm run build
pnpm link --global # makes `polpo` available system-wide
node dist/cli/index.js init
node dist/cli/index.js # TUI
node dist/cli/index.js serve # Server mode
Development
pnpm run dev # watch mode
pnpm test # run tests
Verify
polpo --version
polpo --help
Anthropic
OpenAI
Google
Others
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...
export GROQ_API_KEY=gsk_...
export MISTRAL_API_KEY=...
export OPENROUTER_API_KEY=sk-or-...
