> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinkingmach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment Modes

Paperclip supports two runtime modes with different security profiles. Reachability is configured separately with `bind`.

## `local_trusted`

The default mode. Optimized for single-operator local use.

* **Host binding**: loopback only (localhost)
* **Bind**: `loopback`
* **Authentication**: no login required
* **Use case**: local development, solo experimentation
* **Board identity**: auto-created local board user

```sh theme={null}
# Set during onboard
pnpm paperclipai onboard
# Choose "local_trusted"
```

## `authenticated`

Login required. Supports two exposure policies.

### `authenticated` + `private`

For private network access (Tailscale, VPN, LAN).

* **Authentication**: login required via Better Auth
* **URL handling**: auto base URL mode (lower friction)
* **Host trust**: private-host trust policy required
* **Bind**: choose `loopback`, `lan`, `tailnet`, or `custom`

```sh theme={null}
pnpm paperclipai onboard
# Choose "authenticated" -> "private"
```

Allow custom Tailscale hostnames:

```sh theme={null}
npx paperclipai allowed-hostname my-machine
```

### `authenticated` + `public`

For internet-facing deployment.

* **Authentication**: login required
* **URL**: explicit public URL required
* **Security**: stricter deployment checks in doctor
* **Bind**: usually `loopback` behind a reverse proxy; `lan/custom` is advanced

```sh theme={null}
pnpm paperclipai onboard
# Choose "authenticated" -> "public"
```

## Board Claim Flow

When migrating from `local_trusted` to `authenticated`, Paperclip emits a one-time claim URL at startup:

```
/board-claim/<token>?code=<code>
```

A signed-in user visits this URL to claim board ownership. This:

* Promotes the current user to instance admin
* Demotes the auto-created local board admin
* Ensures active company membership for the claiming user

## Changing Modes

Update the deployment mode:

```sh theme={null}
pnpm paperclipai configure --section server
```

Runtime override via environment variable:

```sh theme={null}
PAPERCLIP_DEPLOYMENT_MODE=authenticated PAPERCLIP_BIND=lan pnpm paperclipai run
```