Paperclip Docker Mirror

This repository publishes a Docker image for Paperclip from upstream paperclipai/paperclip.

Upstream source of truth:

• paperclipai/paperclip

Latest image:

• ghcr.io/ben-ranford/paperclip:latest

What It Does

• Runs nightly with GitHub Actions.
• Checks the latest upstream master commit SHA.
• Skips builds when the upstream SHA was already published.
• Clones upstream source at that SHA.
• Applies local patch files from patches/*.patch.
• Builds and pushes multi-arch images to GHCR when a new upstream SHA appears.

Patch files applied during build:

• patches/0002-enable-agent-assignment.patch

Using The Docker Image

Pull:

docker pull ghcr.io/ben-ranford/paperclip:latest

Prepare a writable data directory:

mkdir -p ./data/paperclip
sudo chown -R 1000:1000 ./data/paperclip

The image uses the upstream Paperclip entrypoint and aligns the container user/group with USER_UID/USER_GID when values are provided. Pre-setting volume ownership is still recommended for large data volumes.

Environment Variables

Required:

• BETTER_AUTH_SECRET: auth/session signing secret for authenticated mode.

Common:

• HOST (default: 0.0.0.0)
• PORT (default: 3100)
• PAPERCLIP_HOME (default in image: /paperclip)
• PAPERCLIP_PUBLIC_URL (recommended for callback/link correctness)
• DATABASE_URL (optional; if unset, Paperclip uses embedded PostgreSQL)
• OPENAI_API_KEY (optional; for Codex adapter)
• ANTHROPIC_API_KEY (optional; for Claude adapter)
• USER_UID (default: 1000)
• USER_GID (default: 1000)

Security and deployment:

• PAPERCLIP_DEPLOYMENT_MODE (default: authenticated)
  • authenticated: authentication enabled.
  • local_trusted: non-authenticated local trusted mode.
• PAPERCLIP_DEPLOYMENT_EXPOSURE (default: private)
• PAPERCLIP_AUTH_PUBLIC_BASE_URL (optional explicit auth base URL)
• PAPERCLIP_ALLOWED_HOSTNAMES (optional comma-separated allowlist)
• PAPERCLIP_ALLOW_AGENT_ASSIGN (optional; default: disabled)
  • true: allow agents to assign/reassign issues without tasks:assign.
  • false/unset: keep normal assignment permission checks.

Storage and backups (optional advanced):

• PAPERCLIP_STORAGE_PROVIDER (local_disk or s3)
• PAPERCLIP_STORAGE_S3_BUCKET, PAPERCLIP_STORAGE_S3_REGION, PAPERCLIP_STORAGE_S3_ENDPOINT
• AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
• PAPERCLIP_DB_BACKUP_ENABLED, PAPERCLIP_DB_BACKUP_INTERVAL_MINUTES, PAPERCLIP_DB_BACKUP_RETENTION_DAYS

Example: Embedded PostgreSQL

docker run --rm \
  -p 3100:3100 \
  -e BETTER_AUTH_SECRET=replace-with-strong-secret \
  -e PAPERCLIP_PUBLIC_URL=http://localhost:3100 \
  -e PAPERCLIP_ALLOW_AGENT_ASSIGN=true \
  -v "$(pwd)/data/paperclip:/paperclip" \
  ghcr.io/ben-ranford/paperclip:latest

Example: External PostgreSQL

docker run --rm \
  -p 3100:3100 \
  -e BETTER_AUTH_SECRET=replace-with-strong-secret \
  -e PAPERCLIP_PUBLIC_URL=http://localhost:3100 \
  -e PAPERCLIP_ALLOW_AGENT_ASSIGN=true \
  -e DATABASE_URL=postgres://paperclip:paperclip@host.docker.internal:5432/paperclip \
  -v "$(pwd)/data/paperclip:/paperclip" \
  ghcr.io/ben-ranford/paperclip:latest