How to Configure Paperclip Deployment Modes: Trusted Local vs Authenticated

Set PAPERCLIP_DEPLOYMENT_MODE to local_trusted for solo development, or authenticated with PAPERCLIP_DEPLOYMENT_EXPOSURE set to private or public for team and production deployments.

Paperclip supports two distinct deployment modes that control authentication requirements, network exposure, and security posture. The mode you select determines whether users must log in, which network interfaces the server binds to, and how the instance handles user provisioning. This configuration is managed through environment variables and validated at startup in server/src/config.ts according to the paperclipai/paperclip source code.

Understanding Paperclip Deployment Modes

Paperclip's deployment architecture separates authentication requirements from network exposure, giving you precise control over security boundaries.

Mode	Authentication	Network Binding	Typical Use Case
local_trusted	None (auto-creates local board user)	Loopback only (127.0.0.1)	Solo development on a single machine
authenticated + private	Required (Better Auth)	Private network (Tailscale, VPN, LAN)	Team access behind existing perimeter
authenticated + public	Required (Better Auth)	Internet-facing with explicit public URL	Cloud deployment, external access

The mode selection is stored in PAPERCLIP_DEPLOYMENT_MODE (default: local_trusted). When set to authenticated, the secondary variable PAPERCLIP_DEPLOYMENT_EXPOSURE selects between private and public networking policies. These variables are validated together in server/src/config.ts at lines 60-82 to prevent misconfiguration.

Trusted Local Mode (local_trusted)

Trusted local mode is the default zero-configuration option designed for rapid individual development.

Key characteristics as implemented in the paperclipai/paperclip repository:

• Host binding: Restricted to 127.0.0.1 (loopback interface only)
• Authentication: No login flow; the server automatically creates a single local board user
• Security model: Assumes complete trust of the local machine operator

This mode is documented in docs/deploy/deployment-modes.md (lines 8-16) and the overview table in docs/deploy/overview.md (lines 10-15). Use this mode when you need to start working immediately without configuring identity providers or network infrastructure.

Authenticated Mode (authenticated)

Authenticated mode enforces user login through Better Auth (JWT-based sessions) and is required for any multi-user deployment.

Private Exposure

Setting PAPERCLIP_DEPLOYMENT_EXPOSURE=private configures Paperclip for operation behind an existing private network perimeter:

• Suitable for Tailscale networks, corporate VPNs, or restricted LAN segments
• Does not require public internet routing
• Relies on external network infrastructure for access control

Public Exposure

Setting PAPERCLIP_DEPLOYMENT_EXPOSURE=public prepares Paperclip for direct internet exposure:

• Requires explicit PAPERCLIP_PUBLIC_URL configuration
• Enables stricter security validations at startup
• Designed for cloud VPS, container platforms, or dedicated server deployments

The detailed behavior for each exposure variant is documented in docs/deploy/deployment-modes.md (lines 24-56).

How to Configure Paperclip Deployment Modes

Three methods control the active deployment mode: interactive onboarding, post-installation configuration, and runtime environment variables.

Method 1: Configure During Onboarding

The Paperclip CLI provides an interactive mode selector during initial setup:

pnpm paperclipai onboard

The onboarding implementation in cli/src/commands/onboard.ts (lines 81-87) reads your selection and persists it to the server configuration.

Method 2: Reconfigure After Installation

Change modes on an existing installation:

pnpm paperclipai configure --section server

This command launches an interactive prompt to update the deployment mode stored in the server configuration file. The implementation resides in cli/src/commands/configure.ts.

Method 3: Runtime Environment Variables

Override configuration at startup by setting environment variables before invoking the run command:

# Trusted local (default behavior)

PAPERCLIP_DEPLOYMENT_MODE=local_trusted pnpm paperclipai run

# Authenticated private deployment

PAPERCLIP_DEPLOYMENT_MODE=authenticated \
PAPERCLIP_DEPLOYMENT_EXPOSURE=private \
pnpm paperclipai run

# Authenticated public deployment with custom URL

PAPERCLIP_DEPLOYMENT_MODE=authenticated \
PAPERCLIP_DEPLOYMENT_EXPOSURE=public \
PAPERCLIP_PUBLIC_URL=https://paperclip.myorg.com \
pnpm paperclipai run

The complete environment variable reference is maintained in docs/deploy/environment-variables.md (lines 18-21).

Board Claim Flow: Migrating to Authenticated Mode

When transitioning from local_trusted to authenticated, Paperclip emits a one-time board-claim URL at server startup. As documented in docs/deploy/deployment-modes.md (lines 62-74):

1. Start the server in authenticated mode
2. Visit the claim URL printed to stdout
3. Sign in via Better Auth
4. The signed-in user is promoted to instance admin
5. The auto-created local board admin is demoted

This flow prevents lockout when converting an existing local installation to multi-user operation.

Validation and Safety Mechanisms

The loadConfig() function in server/src/config.ts enforces deployment mode constraints through validateConfiguredBindMode (lines 68-70). Invalid combinations—such as attempting to bind a local_trusted instance to a public interface—trigger immediate startup failures rather than silent security degradation.

Key validation checks include:

• Prohibition of public network binding in local_trusted mode
• Requirement of PAPERCLIP_PUBLIC_URL for public exposure
• Consistency between deployment mode and authentication provider configuration

These validations ensure that accidental misconfiguration cannot expose an unauthenticated Paperclip instance to untrusted networks.

Summary

• Default mode: local_trusted requires no configuration and binds to localhost only
• Team deployments: Use authenticated + private with existing private network infrastructure
• Cloud deployments: Use authenticated + public with explicit public URL configuration
• Configuration methods: Interactive onboarding, configure CLI command, or environment variables
• Migration safety: Board claim flow prevents admin lockout when switching from local to authenticated
• Validation: Startup checks in server/src/config.ts reject dangerous configuration combinations

Frequently Asked Questions

What happens if I don't set any deployment mode variables?

Paperclip defaults to local_trusted mode, binding only to 127.0.0.1 with automatic single-user creation. No login is required. This behavior is hardcoded in server/src/config.ts and documented in docs/deploy/deployment-modes.md.

Can I switch from authenticated back to local_trusted mode?

Yes. Set PAPERCLIP_DEPLOYMENT_MODE=local_trusted and restart. However, existing Better Auth user sessions will become invalid, and the instance reverts to auto-creating a local board user. Review docs/deploy/deployment-modes.md for implications on existing data.

Do I need a separate identity provider for authenticated mode?

No. Paperclip uses Better Auth, which provides JWT-based sessions and authentication flows without requiring external OAuth providers. The authentication system is initialized based on deployment mode in server/src/config.ts.

What is the difference between private and public exposure in authenticated mode?

private assumes the instance runs behind an existing network perimeter (Tailscale, VPN, corporate LAN) and does not validate public reachability. public requires PAPERCLIP_PUBLIC_URL and enables additional security checks for internet-facing operation. Both modes require login; the distinction is network topology and validation strictness.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}