← All articles

Essential variables

These are the variables you need to set for any production Paperclip deployment.

BETTER_AUTH_SECRET

Required. Signs all authentication tokens (sessions, API keys, JWTs). Must be a long random string.

BETTER_AUTH_SECRET=your_random_64_character_string_here

Generate one:

openssl rand -hex 32
# Example output: a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

If this is missing or weak, sessions won't work correctly. Never commit this to version control.

PAPERCLIP_DATA_DIR

Where Paperclip stores its SQLite database and persistent data.

PAPERCLIP_DATA_DIR=/opt/paperclip/data

Defaults to ~/.paperclip/instances/default/data on local installs. On VPS deployments, set this explicitly to a path with persistent storage.

NODE_ENV

NODE_ENV=production

Set to production for all deployed instances. Enables production optimizations and disables development-only features.

Network configuration

PAPERCLIP_LISTEN_PORT

The port Paperclip listens on.

PAPERCLIP_LISTEN_PORT=3100

Default: 3100. Change this if port 3100 is already in use on your server. When running behind nginx, keep Paperclip on 3100 and let nginx handle 80/443.

PAPERCLIP_LISTEN_HOST

The network interface Paperclip binds to.

# Only accessible from localhost (recommended when using nginx)
PAPERCLIP_LISTEN_HOST=127.0.0.1

# Accessible from all network interfaces (if no reverse proxy)
PAPERCLIP_LISTEN_HOST=0.0.0.0

Default: 127.0.0.1. If you're using nginx as a reverse proxy (recommended), keep this as 127.0.0.1. Only set to 0.0.0.0 if Paperclip needs to be directly accessible without a proxy.

Agent authentication

PAPERCLIP_AGENT_JWT_SECRET

Secret for signing agent JWT tokens used in local adapters (claude_local, codex_local). Defaults to BETTER_AUTH_SECRET if not set.

PAPERCLIP_AGENT_JWT_SECRET=your_separate_agent_jwt_secret

Setting this separately from BETTER_AUTH_SECRET lets you rotate one without affecting the other.

PAPERCLIP_AGENT_JWT_TTL_SECONDS

How long agent JWTs stay valid.

PAPERCLIP_AGENT_JWT_TTL_SECONDS=172800  # 48 hours (default)

Default: 172800 (48 hours). Adjust if you need longer or shorter token lifetimes.

Database

By default, Paperclip uses SQLite stored at PAPERCLIP_DATA_DIR. For larger deployments, you can configure a Postgres database.

DATABASE_URL

PostgreSQL connection string (optional, replaces SQLite).

DATABASE_URL=postgresql://user:password@localhost:5432/paperclip

When set, Paperclip uses Postgres instead of SQLite. SQLite works well for small teams; use Postgres if you need concurrent writes at scale.

Secrets management

PAPERCLIP_SECRETS_PROVIDER

How secrets (API keys for agents) are stored.

PAPERCLIP_SECRETS_PROVIDER=local_encrypted  # Default

Options:

• local_encrypted — Encrypts secrets with a master key stored at PAPERCLIP_SECRETS_MASTER_KEY_FILE
• env — Reads secrets from environment variables (useful for cloud secret managers)
• plaintext — No encryption (development only, never use in production)

PAPERCLIP_SECRETS_MASTER_KEY_FILE

Path to the encryption master key file used by local_encrypted provider.

PAPERCLIP_SECRETS_MASTER_KEY_FILE=/opt/paperclip/secrets/master.key

Default: ~/.paperclip/instances/default/secrets/master.key. Paperclip generates this file on first run. Back it up — losing it means losing access to all encrypted agent secrets.

PAPERCLIP_SECRETS_STRICT_MODE

PAPERCLIP_SECRETS_STRICT_MODE=true  # Fail if secrets can't be read
PAPERCLIP_SECRETS_STRICT_MODE=false  # Log warning and continue

Default: false. Enable in production to catch configuration problems early.

UI development

PAPERCLIP_UI_DEV_MIDDLEWARE

PAPERCLIP_UI_DEV_MIDDLEWARE=true

Enables the Vite dev server middleware for UI hot reloading. Only relevant for local Paperclip development — never set in production.

Migration

PAPERCLIP_MIGRATION_PROMPT

PAPERCLIP_MIGRATION_PROMPT=never   # Auto-apply without asking
PAPERCLIP_MIGRATION_PROMPT=always  # Always prompt

Default: always. Set to never in automated deployments where you can't interact with the prompt.

PAPERCLIP_MIGRATION_AUTO_APPLY

PAPERCLIP_MIGRATION_AUTO_APPLY=true

Combined with PAPERCLIP_MIGRATION_PROMPT=never, this automatically applies database migrations on startup. Useful for Docker/CI deployments.

Complete production .env example

# Core
NODE_ENV=production
BETTER_AUTH_SECRET=your_64_char_random_string_here

# Storage
PAPERCLIP_DATA_DIR=/opt/paperclip/data
PAPERCLIP_SECRETS_MASTER_KEY_FILE=/opt/paperclip/secrets/master.key
PAPERCLIP_SECRETS_PROVIDER=local_encrypted
PAPERCLIP_SECRETS_STRICT_MODE=true

# Network
PAPERCLIP_LISTEN_PORT=3100
PAPERCLIP_LISTEN_HOST=127.0.0.1

# Agent auth
PAPERCLIP_AGENT_JWT_SECRET=your_separate_agent_jwt_secret
PAPERCLIP_AGENT_JWT_TTL_SECONDS=172800

# Database migrations
PAPERCLIP_MIGRATION_PROMPT=never
PAPERCLIP_MIGRATION_AUTO_APPLY=true

Setting variables on different platforms

Systemd service: Use EnvironmentFile=/opt/paperclip/.env in your .service file.

Docker Compose: Use env_file: .env or define under environment: in docker-compose.yml.

Railway: Add variables in the service's Variables tab in the Railway dashboard.

Fly.io: Use fly secrets set KEY=value for secrets, or add to the [env] block in fly.toml for non-sensitive variables.

Render: Set under Environment → Environment Variables in the service settings.

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.