ake/paperclip
1
0
Fork 0
mirror of https://github.com/alkimake/paperclip.git synced 2026-06-14 01:50:39 +09:00
Code Issues Projects Releases Packages Wiki Activity

Introduce bind presets for deployment setup

Browse source 
Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
dotta 2026-04-10 07:32:16 -05:00 • committed by Dotta
parent e1bf9d66a7
commit 2a84e53c1b
35 changed files with 915 additions and 176 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/cli/setup-commands.md
View file

@ -89,6 +89,8 @@ Show resolved environment configuration:
pnpm paperclipai env
```
This now includes bind-oriented deployment settings such as `PAPERCLIP_BIND` and `PAPERCLIP_BIND_HOST` when configured.
## `paperclipai allowed-hostname`
Allow a private hostname for authenticated/private mode:

7
docs/deploy/deployment-modes.md
View file

@ -3,13 +3,14 @@ title: Deployment Modes
summary: local_trusted vs authenticated (private/public)
---
Paperclip supports two runtime modes with different security profiles.
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
@ -31,6 +32,7 @@ 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
pnpm paperclipai onboard
@ -50,6 +52,7 @@ 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
pnpm paperclipai onboard
@ -81,5 +84,5 @@ pnpm paperclipai configure --section server
Runtime override via environment variable:
```sh
PAPERCLIP_DEPLOYMENT_MODE=authenticated pnpm paperclipai run
PAPERCLIP_DEPLOYMENT_MODE=authenticated PAPERCLIP_BIND=lan pnpm paperclipai run
```

5
docs/deploy/environment-variables.md
View file

@ -10,11 +10,14 @@ All environment variables that Paperclip uses for server configuration.
| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3100` | Server port |
| `HOST` | `127.0.0.1` | Server host binding |
| `PAPERCLIP_BIND` | `loopback` | Reachability preset: `loopback`, `lan`, `tailnet`, or `custom` |
| `PAPERCLIP_BIND_HOST` | (unset) | Required when `PAPERCLIP_BIND=custom` |
| `HOST` | `127.0.0.1` | Legacy host override; prefer `PAPERCLIP_BIND` for new setups |
| `DATABASE_URL` | (embedded) | PostgreSQL connection string |
| `PAPERCLIP_HOME` | `~/.paperclip` | Base directory for all Paperclip data |
| `PAPERCLIP_INSTANCE_ID` | `default` | Instance identifier (for multiple local instances) |
| `PAPERCLIP_DEPLOYMENT_MODE` | `local_trusted` | Runtime mode override |
| `PAPERCLIP_DEPLOYMENT_EXPOSURE` | `private` | Exposure policy when deployment mode is `authenticated` |
## Secrets

25
docs/deploy/local-development.md
View file

@ -38,19 +38,26 @@ This does:
2. Runs `paperclipai doctor` with repair enabled
3. Starts the server when checks pass
## Tailscale/Private Auth Dev Mode
## Bind Presets In Dev
To run in `authenticated/private` mode for network access:
Default `pnpm dev` stays in `local_trusted` with loopback-only binding.
To open Paperclip to a private network with login enabled:
```sh
pnpm dev --bind lan
```
For Tailscale-only binding on a detected tailnet address:
```sh
pnpm dev --bind tailnet
```
Legacy aliases still work and map to the older broad private-network behavior:
```sh
pnpm dev --tailscale-auth
```
This binds the server to `0.0.0.0` for private-network access.
Alias:
```sh
pnpm dev --authenticated-private
```

19
docs/deploy/tailscale-private-access.md
View file

@ -1,6 +1,6 @@
---
title: Tailscale Private Access
summary: Run Paperclip with Tailscale-friendly host binding and connect from other devices
summary: Run Paperclip with Tailscale-friendly bind presets and connect from other devices
---
Use this when you want to access Paperclip over Tailscale (or a private LAN/VPN) instead of only `localhost`.
@ -8,20 +8,25 @@ Use this when you want to access Paperclip over Tailscale (or a private LAN/VPN)
## 1. Start Paperclip in private authenticated mode
```sh
pnpm dev --tailscale-auth
pnpm dev --bind tailnet
```
This configures:
Recommended behavior:
- `PAPERCLIP_DEPLOYMENT_MODE=authenticated`
- `PAPERCLIP_DEPLOYMENT_EXPOSURE=private`
- `PAPERCLIP_AUTH_BASE_URL_MODE=auto`
- `HOST=0.0.0.0` (bind on all interfaces)
- `PAPERCLIP_BIND=tailnet`
Equivalent flag:
If you want the old broad private-network behavior instead, use:
```sh
pnpm dev --bind lan
```
Legacy aliases still map to `authenticated/private + bind=lan`:
pnpm dev --authenticated-private
pnpm dev --tailscale-auth
```
## 2. Find your reachable Tailscale address
@ -73,5 +78,5 @@ Expected result:
## Troubleshooting
- Login or redirect errors on a private hostname: add it with `paperclipai allowed-hostname`.
- App only works on `localhost`: make sure you started with `--tailscale-auth` (or set `HOST=0.0.0.0` in private mode).
- App only works on `localhost`: make sure you started with `--bind lan` or `--bind tailnet` instead of plain `pnpm dev`.
- Can connect locally but not remotely: verify both devices are on the same Tailscale network and port `3100` is reachable.