Paperclip

Paperclip Docker Deployment👨‍💻

Paperclip ships as a Docker image, making containerized deployment the standard path for both development and production. The Docker setup bundles the Paperclip control plane, agent runtime, and dashboard into a single container (or multi-container compose stack for production). This page covers everything from the initial docker run to a production-ready Docker Compose configuration with persistent storage, proper networking, environment variables, and scaling. If you ran npx paperclipai onboard and chose Docker, this is the reference for what that generated and how to customize it.

Key Takeaways

  • 1Paperclip publishes an official Docker image at ghcr.io/paperclipai/paperclip. The image includes the control plane (API server, scheduler, governance engine), agent runtime, and web dashboard. For development, a single container is enough. For production, split into separate services.
  • 2The `npx paperclipai onboard` CLI generates a docker-compose.yml with sensible defaults: Paperclip server, PostgreSQL for state, Redis for job queues, and optional Qdrant for vector search. This is the fastest way to get a local Paperclip instance running.
  • 3Persistent volumes are critical. Paperclip stores agent workspaces (SOUL.md, MEMORY.md, sessions) on disk. Without a volume mount, you lose all agent memory and configuration when the container restarts. Map /data to a Docker volume or host directory.
  • 4Environment variables configure API keys, database URLs, and feature flags. At minimum, set PAPERCLIP_DB_URL (PostgreSQL connection), PAPERCLIP_REDIS_URL (job queue), and at least one LLM provider key (OPENAI_API_KEY or ANTHROPIC_API_KEY). Store secrets in Docker secrets or a .env file excluded from version control.
  • 5Networking: the Paperclip dashboard runs on port 3000 by default, the API on port 3001. In production, put both behind a reverse proxy (nginx, Caddy, Traefik) with TLS termination. Never expose the API port directly to the internet without authentication.
  • 6Scaling: Paperclip supports horizontal scaling of the agent runtime. Run multiple runtime containers behind a load balancer while keeping a single control plane instance. The control plane uses PostgreSQL for coordination, so runtime containers can be stateless.

Master paperclip docker deployment

Take the Paperclip Setup course with hands-on lessons and challenges.

Examples

Quick start with docker run

bash

The simplest way to run Paperclip. Uses SQLite for storage (fine for development, not for production). The -v flag creates a named volume for persistent data. Without it, agent workspaces and memory would be lost on container restart.

Production Docker Compose setup

yaml

Production setup with PostgreSQL for state, Redis for job queues and agent scheduling. Health checks ensure Paperclip waits for PostgreSQL before starting. All secrets come from environment variables (use a .env file locally, Docker secrets in production). Named volumes persist data across container restarts and upgrades.

Environment variables reference

bash

Environment variables control all Paperclip configuration. PAPERCLIP_SECRET_KEY signs JWTs for dashboard authentication — generate a random string and never share it. CORS_ORIGINS restricts which domains can call the API. Set LOG_LEVEL to 'debug' during initial setup, then 'info' or 'warn' for production.

Adding a reverse proxy with Caddy

yaml

Caddy provides automatic HTTPS via Let's Encrypt. Route dashboard and API traffic through a single domain with path-based routing. This eliminates the need to expose ports 3000 and 3001 directly — remove those port mappings from the paperclip service after adding Caddy.

Upgrading Paperclip in Docker

bash

Always check release notes before upgrading — some versions require database migrations. The named volumes ensure your data survives the upgrade. Run migrations after restarting the container. Check logs to verify the new version started cleanly.

Common Mistakes

Mistake:

Running Paperclip in Docker without a persistent volume, losing all agent workspaces, memory, and session data when the container restarts

Fix:

Always mount a volume to /data: `-v paperclip-data:/data`. This preserves agent configurations (SOUL.md, MEMORY.md), session history, and uploaded files across container restarts and upgrades.

Mistake:

Using SQLite in production, which does not support concurrent writes from multiple agent processes

Fix:

SQLite is fine for development and single-agent setups. For production with multiple agents running heartbeats and cron jobs concurrently, use PostgreSQL. Set PAPERCLIP_DB_URL to a PostgreSQL connection string.

Mistake:

Exposing the Paperclip API port (3001) directly to the internet without TLS or authentication

Fix:

Put Paperclip behind a reverse proxy (Caddy, nginx, Traefik) with TLS termination. The API port should only be accessible within the Docker network. Remove the port mapping from docker-compose.yml and route traffic through the proxy.

Mistake:

Hardcoding API keys in docker-compose.yml or Dockerfile instead of using environment variables or Docker secrets

Fix:

Use a .env file (excluded from version control) for local development and Docker secrets for production. Never commit API keys to your repository — even in a private repo, credentials in git history are a persistent risk.

Best Practices

  • Start with `npx paperclipai onboard` which generates a docker-compose.yml tailored to your setup. Customize from there rather than writing the compose file from scratch.
  • Use Docker health checks for PostgreSQL and Redis. Paperclip should not start until its dependencies are ready. The depends_on condition ensures correct startup order.
  • Pin the Paperclip image to a specific version tag in production (e.g., ghcr.io/paperclipai/paperclip:2.1.0) instead of :latest. This prevents unexpected breaking changes during redeployment.
  • Back up the /data volume and PostgreSQL database regularly. Agent workspaces contain irreplaceable configurations (SOUL.md, MEMORY.md) that represent significant tuning effort.
  • Set resource limits on the Paperclip container (deploy.resources.limits in compose) to prevent a runaway agent from consuming all host memory or CPU.
  • Monitor container logs with `docker compose logs -f paperclip` during initial setup. Watch for connection errors to PostgreSQL, Redis, or LLM providers — these are the most common deployment issues.

Summary

Paperclip deploys as a Docker container with PostgreSQL for state and Redis for job queues. Use `npx paperclipai onboard` to generate a Docker Compose setup, then customize for production: add persistent volumes, configure environment variables for API keys and secrets, put the dashboard and API behind a reverse proxy with TLS, and pin image versions. Always mount /data for persistent agent workspaces. Use PostgreSQL (not SQLite) for production workloads with concurrent agents.

Practice Paperclip with hands-on challenges

Learn paperclip docker deployment hands-on in your IDE

Interactive lessons and challenges on Stanza, practice in VS Code, Cursor, or the web.

Related Concepts

Paperclip Org ChartsPaperclip HeartbeatsOpenclaw DeploymentOpenclaw Deployment Production

Master Paperclip with Stanza

Interactive lessons and challenges, right in your code editor.

Check the free courses. No credit card.