netspeedy/paperclip repository overview

netspeedy/paperclip is an automated multi-architecture container image for Paperclip⁠, built from upstream release source without vendoring the full repository into this packaging repo.

This image is intended to feel like a polished upstream-style container:

• stable upstream tags are preserved as published, for example v2026.403.0
• latest tracks the newest stable upstream v... tag
• images are built automatically from upstream release archives with Docker buildx
• the upstream tag's own Dockerfile is used unless a narrowly-scoped compatibility rewrite is required during source preparation

⁠Supported Platforms

• linux/amd64
• linux/arm64

⁠Tags

• netspeedy/paperclip:latest
• netspeedy/paperclip:v2026.403.0

⁠Image Highlights

• Better Auth-enabled Paperclip server and UI
• Embedded PostgreSQL available by default when DATABASE_URL is unset
• First-boot auth secret bootstrap for simple local runs
• Automatic non-interactive onboarding when config.json is missing
• First admin bootstrap invite printed in logs for authenticated embedded-PostgreSQL first boots
• Multi-arch automated builds from upstream source
• Common agent tools preinstalled: git, gh, curl, wget, ripgrep, python3
• Local agent CLIs preinstalled: claude, codex, opencode

⁠First-Boot Behavior

On a fresh /paperclip volume, this image will:

1. Start embedded PostgreSQL automatically if DATABASE_URL is not set.
2. Generate and persist PAPERCLIP_AGENT_JWT_SECRET in /paperclip/instances/default/.env if neither BETTER_AUTH_SECRET nor PAPERCLIP_AGENT_JWT_SECRET is provided.
3. Default PAPERCLIP_PUBLIC_URL to http://localhost:$PORT when no explicit auth/public URL env vars are set.
4. Run paperclipai onboard --yes automatically when /paperclip/instances/default/config.json is missing.
5. In authenticated mode with embedded PostgreSQL, print a bootstrap CEO invite URL in the container logs once the server is ready.

This makes docker run and small Compose setups work out of the box while still allowing explicit production settings.

If DATABASE_URL is set, first-boot auto-onboarding still runs when config.json is missing. In that case Paperclip writes a PostgreSQL-backed config instead of an embedded-PostgreSQL one, and startup depends on the external database already being reachable.

⁠Persistent Data

Mount /paperclip to persistent storage.

This directory holds:

• embedded PostgreSQL data when DATABASE_URL is unset
• uploaded assets and local storage state
• local encrypted secrets key material and related runtime state
• generated .env bootstrap values such as PAPERCLIP_AGENT_JWT_SECRET
• backups and instance metadata

⁠Quick Start

mkdir -p ./data/paperclip

docker run --name paperclip \
  -p 3100:3100 \
  -v "$(pwd)/data/paperclip:/paperclip" \
  netspeedy/paperclip:latest

Open http://localhost:3100.

For a fresh authenticated first boot, follow the container logs and open the printed CEO invite URL to claim the first admin account:

docker logs -f paperclip

The invite URL is printed after Paperclip finishes first-run setup.

⁠Docker Compose

⁠Local Quickstart

services:
  paperclip:
    image: netspeedy/paperclip:latest
    container_name: paperclip
    restart: unless-stopped
    ports:
      - "3100:3100"
    environment:
      HOST: 0.0.0.0
      # Set this when the app is reached via a different host or port.
      # PAPERCLIP_PUBLIC_URL: https://paperclip.example.com
      # Optional local adapter credentials:
      # OPENAI_API_KEY: ${OPENAI_API_KEY}
      # ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
    volumes:
      - ./data/paperclip:/paperclip

Start it with:

docker compose up -d
docker compose logs -f paperclip

⁠External PostgreSQL

If you prefer a separate PostgreSQL container or managed database, set DATABASE_URL. Even then, keep the /paperclip mount for files, secrets, backups, and instance state.

On a fresh /paperclip volume, this path still auto-runs paperclipai onboard --yes and writes config.json on first boot. In authenticated mode, the first admin bootstrap invite should also be created, but your external PostgreSQL service must be available before Paperclip starts.

services:
  paperclip:
    image: netspeedy/paperclip:latest
    container_name: paperclip
    restart: unless-stopped
    depends_on:
      - postgres
    ports:
      - "3100:3100"
    environment:
      HOST: 0.0.0.0
      DATABASE_URL: postgres://paperclip:paperclip@postgres:5432/paperclip
      PAPERCLIP_PUBLIC_URL: https://paperclip.example.com
      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
    volumes:
      - ./data/paperclip:/paperclip

  postgres:
    image: postgres:17
    container_name: paperclip-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: paperclip
      POSTGRES_PASSWORD: paperclip
      POSTGRES_DB: paperclip
    volumes:
      - ./data/postgres:/var/lib/postgresql/data

⁠Common Runtime Environment Variables

Common notes:

• DATABASE_URL is optional in this image. Embedded PostgreSQL is enabled.
• For non-localhost deployments, set PAPERCLIP_PUBLIC_URL explicitly.
• For production-style deployments, set BETTER_AUTH_SECRET explicitly.
• OPENAI_API_KEY, ANTHROPIC_API_KEY, DATABASE_URL, HOST, PORT, SERVE_UI, PAPERCLIP_DEPLOYMENT_MODE, PAPERCLIP_DEPLOYMENT_EXPOSURE, PAPERCLIP_PUBLIC_URL, BETTER_AUTH_SECRET, and PAPERCLIP_AGENT_JWT_SECRET are upstream-supported runtime variables.
• PAPERCLIP_AUTO_ONBOARD and PAPERCLIP_AUTO_BOOTSTRAP_CEO, plus the automatic localhost/auth-secret defaults, are packaging-specific conveniences provided by this image.

⁠Build Arguments

The image supports these Docker build arguments:

Example:

docker build -t paperclip-local \
  --build-arg USER_UID=$(id -u) \
  --build-arg USER_GID=$(id -g) \
  .

⁠Automated Build Provenance

This packaging repo builds from upstream Paperclip release archives using:

• .gitlab/scripts/prepare_source.py to fetch and prepare the upstream source
• .gitlab/scripts/docker_build.py to run docker buildx
• upstream release Docker assets for the resolved tag

The published image is labeled with standard OCI metadata including source URL, project URL, vendor, title, and upstream version.

⁠Notes

• latest follows the newest stable upstream v... release.
• Upstream canary tags are not published unchanged because Docker tags cannot contain /.
• This image is based directly on upstream source and intentionally keeps local first-run behavior ergonomic for both docker run and Compose users.