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

> Understand Paperclip deployment modes local_trusted, authenticated, and private/public. Choose the right security for your project from solo dev to public SaaS.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: deep-dive
- Published: 2026-08-18

---

**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`](https://github.com/paperclipai/paperclip/blob/main/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.

```bash

# 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`](https://github.com/paperclipai/paperclip/blob/main/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

```bash

# 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`](https://github.com/paperclipai/paperclip/blob/main/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.

```bash

# 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:

```bash

# Interactive reconfiguration

pnpm paperclipai configure --section server

```

For temporary overrides without persisting changes:

```bash

# 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`](https://github.com/paperclipai/paperclip/blob/main/docs/deploy/deployment-modes.md)
- **`authenticated + private`** enforces Better Auth login for VPN/Tailscale/LAN deployments, documented in [`docs/deploy/overview.md`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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.