Self-hosting

Self-hosting runs the open-source Polpo runtime with your project directory, storage backend, model credentials, and optional single-tenant dashboard. No Polpo Cloud account is required.

Requirements

Docker, or Node.js 20+ with pnpm
a .polpo/ project directory
access to a model gateway or provider credential
PostgreSQL only when storage is set to postgres

Build the Docker image

The open-source repository contains the backend Dockerfile:

git clone https://github.com/lumea-labs/polpo.git
cd polpo
docker build -t polpo-self-hosted .

Current release workflows publish ghcr.io/lumea-labs/polpo-runner, which is the sandbox runner, not the Polpo backend. Build the root Dockerfile for the self-hosted server; do not use the runner image as an API server.

Create a workspace/.polpo/ project as shown in Local Development, then run:

docker run --rm \
  -p 3890:3890 \
  -v "$PWD/workspace:/app/workspace" \
  -e POLPO_API_KEY="replace-with-a-long-random-key" \
  -e AI_GATEWAY_API_KEY="$AI_GATEWAY_API_KEY" \
  polpo-self-hosted

The image uses /app/workspace as WORK_DIR and listens on port 3890.

Runtime and dashboard with Docker Compose

The repository includes a production-oriented Compose example. It keeps PostgreSQL and the runtime on a private network and exposes only the dashboard:

cp docker/self-host/.env.example docker/self-host/.env

Edit docker/self-host/.env. Replace POSTGRES_PASSWORD and POLPO_API_KEY with independent random values, set POLPO_MODEL, and provide the matching model credential. The included example uses AI_GATEWAY_API_KEY for Vercel AI Gateway.

docker compose \
  --env-file docker/self-host/.env \
  -f docker/self-host/compose.example.yml \
  up --build --detach --wait

Open http://localhost:3000. The dashboard proxies runtime REST and completion requests; POLPO_API_KEY stays in the dashboard server process and is not shipped to browser JavaScript. The example mounts docker/self-host/project.example/polpo.json, uses PostgreSQL for runtime state, and persists the workspace in a Docker volume. DATABASE_URL supplies settings.databaseUrl because it is omitted from the project file. Stop the stack without deleting data:

docker compose \
  --env-file docker/self-host/.env \
  -f docker/self-host/compose.example.yml \
  down

Add --volumes only when you intentionally want to delete the PostgreSQL and workspace volumes.

Verify a checkout end to end

The repository also contains an isolated test stack with a deterministic mock model. It is separate from the production example:

corepack enable
pnpm install --frozen-lockfile
pnpm test:self-host

The test builds both images, initializes disposable PostgreSQL storage, verifies authentication, creates an agent, executes a real completion path, checks session persistence and dashboard rendering, then removes its containers and volumes.

Storage backends

Backend	Configuration	Intended deployment
File	`"storage": "file"`	Simple single-instance server
SQLite	`"storage": "sqlite"`	Single-instance database
PostgreSQL	`"storage": "postgres"`	Shared durable database and multi-instance deployments

For PostgreSQL, set settings.databaseUrl or DATABASE_URL. File and SQLite storage do not require a database URL.

Model gateway

For the default Vercel gateway, pass AI_GATEWAY_API_KEY. To use another OpenAI-compatible endpoint, configure its URL and key variable name in the mounted .polpo/polpo.json:

{
  "project": "self-hosted",
  "settings": {
    "gateway": {
      "url": "https://gateway.example.com/v1",
      "apiKeyEnv": "MY_GATEWAY_API_KEY"
    }
  }
}

Then pass MY_GATEWAY_API_KEY to the container. There is no AI_GATEWAY_URL server environment variable. See Model Gateway for provider overrides and local endpoints.

Server environment

Variable	Default	Description
`PORT`	`3890`	HTTP port
`HOST`	`0.0.0.0`	Bind address in the Docker entrypoint
`WORK_DIR`	`/app/workspace`	Directory containing `.polpo/`
`POLPO_API_KEY`	unset	One accepted API key
`POLPO_API_KEYS`	unset	Additional comma-separated accepted API keys for rotation
`CORS_ORIGINS`	unset	Comma-separated allowed origins
`DATABASE_URL`	unset	PostgreSQL URL fallback
`AI_GATEWAY_API_KEY`	unset	Vercel AI Gateway credential

Provider and custom gateway variables configured by the project must also be present in the server process.

Authentication paths

When either API-key variable is set, chat and standard REST routes accept a Bearer token:

curl http://localhost:3890/v1/chat/completions \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent":"agent-1","messages":[{"role":"user","content":"Hello"}]}'

The legacy x-api-key header is also accepted by standard /api/v1 routes:

curl http://localhost:3890/api/v1/agents \
  -H "x-api-key: $POLPO_API_KEY"

Reverse proxy

SSE responses must not be buffered. A minimal nginx location is:

server {
    listen 443 ssl;
    server_name polpo.example.com;

    location / {
        proxy_pass http://127.0.0.1:3890;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Self-hosted execution uses the runtime’s local process isolation by default. The runtime accepts the portable sandbox.isolation policy, but the selected host adapter decides whether reuse and fresh map to separate local processes, containers, or another sandbox provider. Self-hosting does not include the managed Cloud sandbox pool, project provisioning, or operational control plane. The open-source dashboard exposes runtime-scoped views for agents, playground chat, skills, shared memory, files, and sessions. Organization management, billing, managed connections, Cloud provisioning, and other control-plane screens remain Cloud-only.

Getting Started

Platform

Agents

Orchestration

Self-hosting

Requirements

Build the Docker image

Runtime and dashboard with Docker Compose

Verify a checkout end to end

Storage backends

Model gateway

Server environment

Authentication paths

Reverse proxy

​Requirements

​Build the Docker image

​Runtime and dashboard with Docker Compose

​Verify a checkout end to end

​Storage backends

​Model gateway

​Server environment

​Authentication paths

​Reverse proxy

Requirements

Build the Docker image

Runtime and dashboard with Docker Compose

Verify a checkout end to end

Storage backends

Model gateway

Server environment

Authentication paths

Reverse proxy