Environment Variables

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_HIDDEN_SETTINGS`	(unset)	Comma-separated settings surfaces to hide from the UI and floor at the API, for operators hosting Paperclip for others (managed cloud, internal shared server). See Hiding settings surfaces.

Hiding settings surfaces

PAPERCLIP_HIDDEN_SETTINGS takes keys from the registry in packages/shared/src/settings-visibility.ts:

Any instance settings page: instance.profile, instance.environments, instance.access, instance.heartbeats, instance.experimental, instance.plugins, instance.adapters — removed from navigation and routing (the General page is the settings root and stays visible). Hiding instance.access, instance.plugins, or instance.adapters also floors their management endpoints with 403 settings_operator_managed; hiding instance.experimental floors every experimental toggle write.
Any Instance → General section: instance.general.censorUsernameInLogs, instance.general.keyboardShortcuts, instance.general.backupRetention, instance.general.feedbackDataSharingPreference (each also rejects value-changing writes via PATCH /api/instance/settings/general), plus the UI-only instance.general.deploymentStatus and instance.general.signOut.
Any experimental toggle: instance.experimental.<flagKey> (e.g. instance.experimental.enableSmokeLab) — the card disappears and value-changing writes are rejected.

Unknown keys are logged and ignored, so one list can be rolled across a fleet of mixed app versions. With the variable unset nothing is hidden and behavior is identical to earlier releases. Hiding a toggle does not change its value; pair hiding with the desired default where it matters.

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)

​Server Configuration

​Hiding settings surfaces

​Secrets

​Agent Runtime (Injected into agent processes)

​LLM Provider Keys (for adapters)

Server Configuration

Hiding settings surfaces

Secrets

Agent Runtime (Injected into agent processes)

LLM Provider Keys (for adapters)