Paperclip Deployment Modes Explained: `local_trusted`, `authenticated`, and `private/public` Configuration

Paperclip supports three deployment modes—local_trusted, authenticated + private, and authenticated + public—each designed for specific security requirements ranging from solo development to public SaaS hosting.

The paperclipai/paperclip repository provides flexible deployment configurations that control authentication requirements and network accessibility. These modes are configured during the paperclipai onboard wizard or set via environment variables at runtime, allowing operators to match their security posture to their infrastructure.

The Three Paperclip Deployment Modes

Paperclip's deployment architecture separates authentication (who can access) from network reachability (where access originates). This creates three distinct operational modes:

1. local_trusted – No Authentication, Loopback Only

The local_trusted mode eliminates login friction for single-operator scenarios. In docs/deploy/deployment-modes.md, this is defined as the default onboarding option for development environments.

Attribute	Configuration
Authentication	None required
Network binding	loopback (localhost only)
Board identity	Auto-created as local board user

Use this mode when prototyping, scripting, or running Paperclip on a personal workstation where remote access is unnecessary. The instance binds exclusively to 127.0.0.1, making it unreachable from other machines.

# Select during onboarding

pnpm paperclipai onboard

# → choose "local_trusted"

# Or override temporarily

PAPERCLIP_DEPLOYMENT_MODE=local_trusted pnpm paperclipai run

2. authenticated + private – Login Required, Private Network

Production deployments behind VPNs, Tailscale networks, or corporate LANs use the authenticated + private mode. As documented in docs/deploy/overview.md, this mode enforces Better Auth login while remaining inaccessible from the public internet.

Attribute	Configuration
Authentication	Better Auth login required
Network binding	loopback, lan, tailnet, or custom
Typical use	On-premise, VPN, Tailscale clusters

The PAPERCLIP_BIND environment variable controls network exposure with options including:

• loopback – localhost only
• lan – bind to all LAN interfaces
• tailnet – Tailscale network interface
• custom – specific hostname or interface

# Onboard with authenticated private mode

pnpm paperclipai onboard

# → choose "authenticated" → "private"

# Allow a specific Tailscale hostname

npx paperclipai allowed-hostname my-machine

# Run bound to LAN

PAPERCLIP_DEPLOYMENT_MODE=authenticated PAPERCLIP_BIND=lan pnpm paperclipai run

3. authenticated + public – Login Required, Internet-Facing

Cloud-hosted and SaaS deployments use authenticated + public mode. According to docs/deploy/environment-variables.md, this configuration performs stricter deployment validation (doctor checks) to protect against hostile environments.

Attribute	Configuration
Authentication	Better Auth login required
Network binding	Typically loopback behind reverse proxy
Security level	Hardened with additional validation

This mode is mandatory when exposing Paperclip to the internet, even behind a reverse proxy. The PAPERCLIP_PUBLIC_URL environment variable must be set to your external domain.

# Configure for public deployment

pnpm paperclipai onboard

# → choose "authenticated" → "public"

# Set public URL for reverse proxy setup

export PAPERCLIP_PUBLIC_URL=https://paperclip.mycompany.com
pnpm paperclipai run

How to Select Your Paperclip Deployment Mode

Choose based on your network topology and security requirements:

1. Solo development or experimentation → Use local_trusted. No authentication overhead, localhost-only binding.

2. Production in private network (VPN, Tailscale, LAN) → Use authenticated + private. Enforces login without internet exposure.

3. Multi-tenant SaaS or cloud hosting → Use authenticated + public. Required for internet-facing instances with full security hardening.

Changing Deployment Mode After Onboarding

The paperclipai configure command provides an interactive UI to modify your deployment:

# Interactive reconfiguration

pnpm paperclipai configure --section server

For temporary overrides without persisting changes:

# Authenticated private on LAN

PAPERCLIP_DEPLOYMENT_MODE=authenticated PAPERCLIP_BIND=lan pnpm paperclipai run

# Authenticated public with custom binding

PAPERCLIP_DEPLOYMENT_MODE=authenticated PAPERCLIP_BIND=custom PAPERCLIP_PUBLIC_URL=https://example.com pnpm paperclipai run

Summary

• local_trusted eliminates authentication for localhost-only development, configured in docs/deploy/deployment-modes.md
• authenticated + private enforces Better Auth login for VPN/Tailscale/LAN deployments, documented in docs/deploy/overview.md
• authenticated + public adds hardening checks for internet-facing SaaS hosting, with PAPERCLIP_PUBLIC_URL required per docs/deploy/environment-variables.md
• Switch modes via paperclipai configure --section server or environment variables PAPERCLIP_DEPLOYMENT_MODE and PAPERCLIP_BIND

Frequently Asked Questions

What happens if I expose a local_trusted Paperclip instance to the network?

Do not bind local_trusted to external interfaces. The mode provides no authentication mechanism, making your instance vulnerable to unauthorized access. If you need network reachability, re-onboard with authenticated mode and select private or public accordingly.

Can I run authenticated + private mode without Tailscale or a VPN?

Yes. The lan bind option allows authenticated + private to operate on any private network without internet exposure. However, Tailscale or a VPN provides additional security layers for remote access scenarios.

What's the difference between PAPERCLIP_BIND=loopback in authenticated mode versus local_trusted?

Both bind to localhost, but authenticated + loopback still requires Better Auth login while local_trusted bypasses authentication entirely. Choose local_trusted only when you are the sole operator and want zero friction.

Is authenticated + public required for reverse proxy deployments?

Yes. Any internet-facing deployment—even behind Nginx, Caddy, or Cloudflare—must use authenticated + public mode. This ensures Paperclip performs security validations appropriate for hostile network environments.

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