This page groups the environment surface by operator responsibility. The goal is to keep infra secrets, board auth, agent auth, and provider-connected-account state clearly separated.

​
Core Runtime

VariableDefaultDescription
PORT3100Server port
HOST127.0.0.1Server host binding
DATABASE_URL(embedded)PostgreSQL connection string
PAPERCLIP_HOME~/.paperclipBase directory for all Paperclip data
PAPERCLIP_INSTANCE_IDdefaultInstance identifier for multiple local instances
PAPERCLIP_DEPLOYMENT_MODElocal_trustedRuntime mode override
PAPERCLIP_DEPLOYMENT_EXPOSUREprivateExposure policy when PAPERCLIP_DEPLOYMENT_MODE=authenticated
PAPERCLIP_PUBLIC_URL(derived)Canonical browser URL for the instance
PAPERCLIP_AUTH_BASE_URL_MODEautoWhether Better Auth should derive or require an explicit base URL
PAPERCLIP_AUTH_PUBLIC_BASE_URL(derived)Explicit Better Auth base URL for hosted/public deployments
PAPERCLIP_AUTH_DISABLE_SIGN_UPfalseDisable end-user sign-up for Better Auth sessions
PAPERCLIP_ALLOWED_HOSTNAMES(optional)Extra hostnames trusted in authenticated/private mode
SERVE_UIfalseServe the UI from the API process
DISABLE_TELEMETRYfalseDisable telemetry collection
PORKBUN_API_KEY(optional)DNS automation when sydiolabs.com remains Porkbun-managed
PORKBUN_SECRET_API_KEY(optional)Porkbun API secret paired with PORKBUN_API_KEY
PORKBUN_DOMAINsydiolabs.comAuthoritative domain used for hosted monitor DNS automation

​
Board/Auth Secrets

VariableDefaultDescription
BETTER_AUTH_SECRET(required in authenticated mode)Board/session auth secret for Better Auth
BETTER_AUTH_URL(derived)Better Auth base URL override
BETTER_AUTH_BASE_URL(derived)Better Auth base URL override
BETTER_AUTH_TRUSTED_ORIGINS(optional)Additional trusted origins for Better Auth
PAPERCLIP_AGENT_JWT_SECRET(required for local agent JWTs)Signs the short-lived PAPERCLIP_API_KEY JWT injected into local heartbeat runs
PAPERCLIP_AGENT_JWT_TTL_SECONDS172800Lifetime for the injected agent JWT, in seconds
PAPERCLIP_AGENT_JWT_ISSUERpaperclipJWT issuer claim for injected agent tokens
PAPERCLIP_AGENT_JWT_AUDIENCEpaperclip-apiJWT audience claim for injected agent tokens
PAPERCLIP_SECRETS_MASTER_KEY(from file)32-byte encryption key (base64/hex/raw)
PAPERCLIP_SECRETS_MASTER_KEY_FILE~/.paperclip/.../secrets/master.keyPath to key file
PAPERCLIP_SECRETS_STRICT_MODEfalseRequire secret refs for sensitive env vars

​
Provider / Connector Auth

These are deployment-specific and should be owned by the provider or connector layer, not by Paperclip’s board auth.
VariableDescription
COMPOSIO_*Deployment-specific connected-account configuration, webhook auth, and connection metadata
OPENAI_API_KEYOpenAI API key for Codex Local or hosted containerized adapter runs
ANTHROPIC_API_KEYAnthropic API key for Claude Local adapter runs

​
Agent Runtime

These are set automatically by the server when invoking agents:
VariableDescription
PAPERCLIP_AGENT_IDAgent’s unique ID
PAPERCLIP_COMPANY_IDCompany ID
PAPERCLIP_API_URLPaperclip API base URL
PAPERCLIP_API_KEYShort-lived JWT for API auth
PAPERCLIP_RUN_IDCurrent heartbeat run ID
PAPERCLIP_TASK_IDIssue that triggered this wake
PAPERCLIP_WAKE_REASONWake trigger reason
PAPERCLIP_WAKE_COMMENT_IDComment that triggered this wake
PAPERCLIP_APPROVAL_IDResolved approval ID
PAPERCLIP_APPROVAL_STATUSApproval decision
PAPERCLIP_LINKED_ISSUE_IDSComma-separated linked issue IDs

​
Hosted Ingress

VariableDescription
CLOUDFLARE_TUNNEL_TOKENEnables the cloudflared container when present
OBS_ENABLE_CLOUDFLARE_TUNNELAlternate opt-in flag for the tunnel container
OBS_PROXY_HTTP_PORTLocal-only port override for the hostname router

​
Operator Notes

  • Treat BETTER_AUTH_SECRET, PAPERCLIP_AGENT_JWT_SECRET, database credentials, and provider API keys as separate secret classes.
  • Use PAPERCLIP_PUBLIC_URL as the canonical browser origin when possible.
  • Use PAPERCLIP_ALLOWED_HOSTNAMES only for extra private hostnames in authenticated/private mode.
  • Keep COMPOSIO_* values out of Paperclip’s secret store unless they are explicitly consumed by a deployment script.