Docker Quickstart

Run Paperclip in Docker without installing Node or pnpm locally.

One-liner (build + run)

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

Open: http://localhost:3100

Data persistence:

Embedded PostgreSQL data
uploaded assets
local secrets key
local agent workspace data

All persisted under your bind mount (./data/docker-paperclip in the example above).

Compose Quickstart

docker compose -f docker-compose.quickstart.yml up --build

Defaults:

host port: 3100
persistent data dir: ./data/docker-paperclip

Optional overrides:

PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=./data/pc docker compose -f docker-compose.quickstart.yml up --build

Claude + Codex Local Adapters in Docker

The image pre-installs:

claude (Anthropic Claude Code CLI)
codex (OpenAI Codex CLI)

If you want local adapter runs inside the container, pass API keys when starting the container:

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

Notes:

Without API keys, the app still runs normally.
Adapter environment checks in Paperclip will surface missing auth/CLI prerequisites.

Onboard Smoke Test (Ubuntu + npm only)

Use this when you want to mimic a fresh machine that only has Ubuntu + npm and verify:

npx paperclipai onboard --yes completes
the server binds to 0.0.0.0:3100 so host access works
onboard/run banners and startup logs are visible in your terminal

Build + run:

./scripts/docker-onboard-smoke.sh

Open: http://localhost:3131 (default smoke host port)

Useful overrides:

HOST_PORT=3200 PAPERCLIPAI_VERSION=latest ./scripts/docker-onboard-smoke.sh
PAPERCLIP_DEPLOYMENT_MODE=authenticated PAPERCLIP_DEPLOYMENT_EXPOSURE=private ./scripts/docker-onboard-smoke.sh