environment-variables.md

title	Environment Variables
summary	Full environment variable reference

All environment variables that Paperclip uses for server configuration.

Server Configuration

Variable	Default	Description
PORT	3100	Server port
PAPERCLIP_BIND	loopback	Reachability preset: loopback, lan, tailnet, or custom
PAPERCLIP_BIND_HOST	(unset)	Required when PAPERCLIP_BIND=custom
HOST	127.0.0.1	Legacy host override; prefer PAPERCLIP_BIND for new setups
DATABASE_URL	(embedded)	PostgreSQL connection string
PAPERCLIP_HOME	~/.paperclip	Base directory for all Paperclip data
PAPERCLIP_INSTANCE_ID	default	Instance identifier (for multiple local instances)
PAPERCLIP_DEPLOYMENT_MODE	local_trusted	Runtime mode override
PAPERCLIP_DEPLOYMENT_EXPOSURE	private	Exposure policy when deployment mode is authenticated
PAPERCLIP_API_URL	(auto-derived)	Paperclip API base URL. When set externally (e.g., via Kubernetes ConfigMap, load balancer, or reverse proxy), the server preserves the value instead of deriving it from the listen host and port. Useful for deployments where the public-facing URL differs from the local bind address.
PAPERCLIP_RUNTIME_API_URL	(auto-derived)	Internal Paperclip API base URL for managed runtime bridges and agent processes. An explicit value takes precedence over the auto-derived URL. Set this when the server can reach a different URL than users or remote agents. For example, a container can use http://127.0.0.1:3100 internally while PAPERCLIP_API_URL uses a public reverse-proxy URL.

Secrets

Variable	Default	Description
PAPERCLIP_SECRETS_MASTER_KEY	(from file)	32-byte encryption key (base64/hex/raw)
PAPERCLIP_SECRETS_MASTER_KEY_FILE	~/.paperclip/.../secrets/master.key	Path to key file
PAPERCLIP_SECRETS_STRICT_MODE	false	Require secret refs for sensitive env vars

Agent Runtime (Injected into agent processes)

These are set automatically by the server when invoking agents:

Variable	Description
PAPERCLIP_AGENT_ID	Agent's unique ID
PAPERCLIP_COMPANY_ID	Company ID
PAPERCLIP_API_URL	Paperclip API base URL (inherits the server-level value; see Server Configuration above)
PAPERCLIP_API_KEY	Short-lived JWT for API auth
PAPERCLIP_RUN_ID	Current heartbeat run ID
PAPERCLIP_TASK_ID	Issue that triggered this wake
PAPERCLIP_WAKE_REASON	Wake trigger reason
PAPERCLIP_WAKE_COMMENT_ID	Comment that triggered this wake
PAPERCLIP_APPROVAL_ID	Resolved approval ID
PAPERCLIP_APPROVAL_STATUS	Approval decision
PAPERCLIP_LINKED_ISSUE_IDS	Comma-separated linked issue IDs

LLM Provider Keys (for adapters)

Variable	Description
ANTHROPIC_API_KEY	Anthropic API key (for Claude Code adapter)
OPENAI_API_KEY	OpenAI API key (for Codex adapter)