Run Paperclip in Docker without installing Node or pnpm locally. 
docker compose -f docker-compose.quickstart.yml up --build
Open http://localhost:3100. Defaults:
  • Host port: 3100
  • Data directory: ./data/docker-paperclip
  • Mode: authenticated + private
  • Public URL: http://localhost:3100
Override with environment variables: 
PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=./data/pc \
  docker compose -f docker-compose.quickstart.yml up --build
The quickstart uses the single-service container image and is the fastest way to validate app startup and board auth behavior.

​
Base Compose Stack

docker-compose.yml starts the multi-service base stack:
  • PostgreSQL
  • ClickHouse
  • Paperclip server
It is the right entrypoint when you want to inspect or test the full local control plane with containerized dependencies.

​
Intelligence Overlay

docker-compose.intelligence.yml adds the optional hosted-monitor stack on top of the base compose stack:
  • Langfuse
  • Redash
  • Bytebase
  • ChartDB
  • Gigapipe
  • MindsDB
  • Telescope
  • obs-proxy
  • cloudflared when enabled
Prefer ./scripts/intelligence-stack.sh over raw docker compose for this overlay. The wrapper derives database credentials, creates the tool databases, and only starts cloudflared when you explicitly opt in.

​
Manual Docker Build

docker build -t paperclip-local .
docker run --name paperclip \
  -p 3100:3100 \
  -e HOST=0.0.0.0 \
  -e PAPERCLIP_HOME=/paperclip \
  -v "$(pwd)/data/docker-paperclip:/paperclip" \
  paperclip-local

​
Data Persistence

All data is persisted under the bind mount (./data/docker-paperclip):
  • Embedded PostgreSQL data
  • Uploaded assets
  • Local secrets key
  • Agent workspace data
For the base compose stack, persistent volumes also include pgdata, clickhouse-data, and paperclip-data.

​
Claude and Codex Adapters in Docker

The Docker image pre-installs:
  • claude (Anthropic Claude Code CLI)
  • codex (OpenAI Codex CLI)
Pass API keys to enable local adapter runs inside the container: 
docker run --name paperclip \
  -p 3100:3100 \
  -e HOST=0.0.0.0 \
  -e PAPERCLIP_HOME=/paperclip \
  -e OPENAI_API_KEY=sk-... \
  -e ANTHROPIC_API_KEY=sk-... \
  -v "$(pwd)/data/docker-paperclip:/paperclip" \
  paperclip-local
Without API keys, the app runs normally — adapter environment checks will surface missing prerequisites.

​
Hosted Operators

If you are validating hosted ingress locally, use: 
./scripts/intelligence-stack.sh up
Then browse the stable ingress hostnames through obs-proxy and follow obs-hosted-ingress.md for the Cloudflare-side contract.