# How to Configure Paperclip Deployment Modes: Trusted Local vs Authenticated

> Learn to configure Paperclip deployment modes. Choose trusted local for solo dev or authenticated for teams. Set PAPERCLIP_DEPLOYMENT_MODE and PAPERCLIP_DEPLOYMENT_EXPOSURE for secure deployments.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-16

---

**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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/docs/deploy/deployment-modes.md) (lines 8-16) and the overview table in [`docs/deploy/overview.md`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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:

```bash
pnpm paperclipai onboard

```

The onboarding implementation in [`cli/src/commands/onboard.ts`](https://github.com/paperclipai/paperclip/blob/main/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:

```bash
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`](https://github.com/paperclipai/paperclip/blob/main/cli/src/commands/configure.ts).

### Method 3: Runtime Environment Variables

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

```bash

# Trusted local (default behavior)

PAPERCLIP_DEPLOYMENT_MODE=local_trusted pnpm paperclipai run

```

```bash

# Authenticated private deployment

PAPERCLIP_DEPLOYMENT_MODE=authenticated \
PAPERCLIP_DEPLOYMENT_EXPOSURE=private \
pnpm paperclipai run

```

```bash

# 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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/server/src/config.ts) and documented in [`docs/deploy/deployment-modes.md`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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.