Skip to main content
Polpo is fully open source (MIT). Deploy it on your own servers for full control over data, infrastructure, and costs.

​
Requirements

  • Node.js 20+
  • LLM API key (OpenAI, Anthropic, Google, xAI, OpenRouter, etc.)
  • PostgreSQL (recommended for production)

​
Docker

docker run -d \
  -p 3890:3890 \
  -v $(pwd)/.polpo:/app/.polpo \
  -e ANTHROPIC_API_KEY=sk-... \
  -e POLPO_API_KEY=your-secret-key \
  ghcr.io/lumea-labs/polpo:latest
Or with Docker Compose: 
services:
  polpo:
    image: ghcr.io/lumea-labs/polpo:latest
    ports:
      - "3890:3890"
    volumes:
      - ./.polpo:/app/.polpo
    environment:
      - ANTHROPIC_API_KEY=sk-...
      - POLPO_API_KEY=your-secret-key
      - DATABASE_URL=postgresql://user:pass@db:5432/polpo
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=polpo

volumes:
  pgdata:

​
Storage backends

BackendConfigUse case
File (default)storage: "file"Single instance, simple setup
SQLitestorage: "sqlite"Single instance, better performance
PostgreSQLstorage: "postgres"Production, multi-instance
Configure in .polpo/polpo.json: 
{
  "settings": {
    "storage": "postgres",
    "databaseUrl": "postgresql://user:pass@host:5432/polpo"
  }
}

​
Environment variables

VariableDescription
POLPO_API_KEYProtect the API with a key (required in production)
POLPO_MODELDefault model (e.g. anthropic:claude-sonnet-4-5)
POLPO_CORS_ORIGINSAllowed CORS origins (comma-separated)
DATABASE_URLPostgreSQL connection string
OPENAI_API_KEYOpenAI API key
ANTHROPIC_API_KEYAnthropic API key
XAI_API_KEYxAI API key
OPENROUTER_API_KEYOpenRouter API key

​
Reverse proxy

Behind nginx: 
server {
    listen 443 ssl;
    server_name polpo.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3890;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;  # required for SSE
    }
}

​
When to use cloud instead

Self-hostedCloud
Full controlZero ops
Your infrastructure costsPay-as-you-go
Manual scalingAuto-scale + scale-to-zero
You manage backupsManaged Postgres (Neon)
No sandboxingIsolated sandbox per agent
For local development and testing, see Local Development.