papercliped 2.2.1 → 2.3.0

package/site/docs/host-fly.md

@@ -0,0 +1,129 @@
+# Host Paperclip on Fly.io
+
+Fly.io runs the official Paperclip image on a small virtual machine in the region you pick, with a volume for its data and a free `https://` address. Everything happens from the `fly` command line.
+
+**You'll end up with:** Paperclip at `https://<app>.fly.dev` (or your own domain), always on, connected to Papercliped.
+
+**Time:** about 20 minutes. **Cost:** a `shared-cpu-1x` machine with 2 GB is about $11 a month, `shared-cpu-2x` with 4 GB about $22, plus the volume ($0.15 per GB a month). Fly has no free allowance for new accounts and needs a card. Check Fly's pricing page for current numbers.
+
+## Before you start
+
+Install `flyctl` (see Fly's install page; on macOS `brew install flyctl`, on Linux `curl -L https://fly.io/install.sh | sh`, on Windows `pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"`), then:
+
+```
+fly auth login
+mkdir paperclip-fly && cd paperclip-fly
+```
+
+## 1. Create the app
+
+```
+fly launch --image ghcr.io/paperclipai/paperclip:latest --no-deploy
+```
+
+Pick an app name (this becomes `https://<app>.fly.dev`) and a region near you. Say **no** to any database Fly offers; Paperclip brings its own.
+
+## 2. Create the volume
+
+Use the same region you picked (for example `iad`, `lhr`, `fra`, `syd`):
+
+```
+fly volumes create paperclip_data --size 10 --region iad
+```
+
+## 3. Write `fly.toml`
+
+Replace the file `fly launch` made with this, changing `app`, `primary_region` and the URL:
+
+```
+app = "your-app-name"
+primary_region = "iad"
+
+[build]
+  image = "ghcr.io/paperclipai/paperclip:latest"
+
+[env]
+  PAPERCLIP_DEPLOYMENT_MODE = "authenticated"
+  PAPERCLIP_DEPLOYMENT_EXPOSURE = "public"
+  PAPERCLIP_PUBLIC_URL = "https://your-app-name.fly.dev"
+  PORT = "3100"
+
+[[mounts]]
+  source = "paperclip_data"
+  destination = "/paperclip"
+
+[http_service]
+  internal_port = 3100
+  force_https = true
+  auto_stop_machines = "off"
+  auto_start_machines = true
+  min_machines_running = 1
+
+  [[http_service.checks]]
+    method = "GET"
+    path = "/api/health"
+    interval = "30s"
+    timeout = "5s"
+    grace_period = "60s"
+
+[[vm]]
+  size = "shared-cpu-2x"
+  memory = "4gb"
+```
+
+`auto_stop_machines = "off"` matters: a stopped machine stops your agents mid-task.
+
+## 4. Add the secrets and deploy
+
+```
+fly secrets set BETTER_AUTH_SECRET=$(openssl rand -hex 32) PAPERCLIP_TOOL_ACTION_SIGNING_SECRET=$(openssl rand -hex 32)
+fly deploy --ha=false
+```
+
+Add your agents' keys the same way if you use them: `fly secrets set ANTHROPIC_API_KEY=... OPENAI_API_KEY=...`.
+
+`--ha=false` keeps it to **one machine**: a volume belongs to one machine, and two copies of Paperclip must never share data.
+
+## 5. Create your account
+
+```
+fly ssh console
+```
+
+Inside the machine:
+
+```
+HOME=/paperclip gosu node npx --yes paperclipai auth bootstrap-ceo --data-dir /paperclip --base-url https://your-app-name.fly.dev
+```
+
+Open the invite link it prints, create your account and your first company. Optionally close public sign-ups afterwards: `fly secrets set PAPERCLIP_AUTH_DISABLE_SIGN_UP=true`.
+
+To sign agents in with a subscription instead of keys, run `HOME=/paperclip gosu node claude` (or `codex`) in the same console. The login is saved on the volume.
+
+## 6. Your own domain (optional)
+
+```
+fly certs add paperclip.yourdomain.com
+```
+
+Create the DNS records it prints, then change `PAPERCLIP_PUBLIC_URL` in `fly.toml` to the new address and `fly deploy` again.
+
+## 7. Check and connect
+
+```
+curl https://your-app-name.fly.dev/api/health
+```
+
+You want `"status":"ok"`, `"deploymentExposure":"public"` and `"bootstrapStatus":"ready"`. Then [connect Papercliped](/docs/hosting#connect-papercliped) and send *"Catch me up on my Paperclip."*
+
+## Updates and backups
+
+- **Update:** `fly deploy` pulls the newest `latest` image. It restarts the machine, so runs in progress stop; update when agents are idle.
+- **Backups:** Fly snapshots volumes daily (`fly volumes snapshots list`). Keep your own copy for anything important.
+
+## Troubleshooting
+
+- **Health check failing:** `fly logs`. Usually a missing secret or a public URL without `https://`.
+- **"This hostname is not allowed":** `PAPERCLIP_PUBLIC_URL` doesn't match the address you opened.
+- **Two machines running:** `fly scale count 1`. Never run more than one.
+- More: [Troubleshooting](/docs/troubleshooting).

package/site/docs/host-railway.md

@@ -0,0 +1,105 @@
+# Host Paperclip on Railway
+
+Railway runs the official Paperclip image for you: no server to look after, a free `https://` address, and a dashboard for everything. The fewest steps of any always-on option.
+
+**You'll end up with:** Paperclip at `https://<name>.up.railway.app` (or your own domain), its data on a Railway volume, connected to Papercliped.
+
+**Time:** about 15 minutes. **Cost:** Railway bills by usage. Paperclip with 1–2 GB of memory, always on, is roughly **$10–25 a month** on the Hobby plan ($5 a month including $5 of usage). Railway's free plan is too small for Paperclip (0.5 GB of memory). Check Railway's pricing page for current numbers.
+
+## Before you start
+
+- A Railway account on the **Hobby** plan (or the trial, to try it).
+- Two random secrets. Make each with `openssl rand -hex 32`, or have your password manager generate a 64-character password of letters and numbers.
+
+> **About community templates:** Railway's template gallery has community-made Paperclip templates. They're not made by Paperclip or by us. They can be quicker, but check that they set `PAPERCLIP_DEPLOYMENT_EXPOSURE=public` and attach a volume at `/paperclip`. The steps below use the official image directly, so you know exactly what's running.
+
+## 1. Create the service
+
+1. In Railway, **New Project → Docker Image** (or **Deploy a Docker Image**).
+2. Image: `ghcr.io/paperclipai/paperclip:latest`. Railway creates the service and starts a first deploy; it's fine if that one doesn't work yet.
+
+## 2. Add the volume
+
+Right-click the service (or use the command palette) → **Attach Volume**. Mount path: **`/paperclip`**. This is where Paperclip keeps its database, secrets key, uploads, workspaces and agent logins. Without it, everything is lost on each deploy.
+
+## 3. Get your address
+
+Service → **Settings → Networking → Generate Domain**. If Railway asks for the port, enter **3100**. Note the address, like `https://paperclip-production-1234.up.railway.app`.
+
+Want your own domain? Use **Custom Domain** instead, add the CNAME record Railway shows at your DNS provider, and use that address below.
+
+## 4. Add the settings
+
+Service → **Variables → Raw Editor**, paste and fill in:
+
+```
+PAPERCLIP_DEPLOYMENT_MODE=authenticated
+PAPERCLIP_DEPLOYMENT_EXPOSURE=public
+PAPERCLIP_PUBLIC_URL=https://YOUR-ADDRESS
+BETTER_AUTH_SECRET=YOUR-FIRST-SECRET
+PAPERCLIP_TOOL_ACTION_SIGNING_SECRET=YOUR-SECOND-SECRET
+PORT=3100
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+```
+
+`PAPERCLIP_PUBLIC_URL` must be exactly your address from step 3, with `https://` and no slash at the end. Leave the API keys empty if you'll sign agents in with a subscription (step 7).
+
+**Optional managed database:** add a Postgres from **New → Database → PostgreSQL** and set `DATABASE_URL=${{Postgres.DATABASE_URL}}`. Without it Paperclip uses its built-in Postgres on the volume, which is cheaper and fine for most people.
+
+## 5. Health check and memory
+
+- Service → **Settings → Deploy → Healthcheck Path:** `/api/health`.
+- Keep **serverless / app sleeping off**. A sleeping Paperclip stops your agents.
+- Watch memory in the **Metrics** tab for the first days; you pay per GB used.
+
+Deploy (Railway usually redeploys after variable changes; otherwise press **Deploy**).
+
+## 6. Create your account
+
+Install the Railway CLI (`npm i -g @railway/cli`), then in a terminal:
+
+```
+railway login
+railway link
+railway ssh
+```
+
+Pick your project and service when asked. Inside the container:
+
+```
+HOME=/paperclip gosu node npx --yes paperclipai auth bootstrap-ceo --data-dir /paperclip --base-url https://YOUR-ADDRESS
+```
+
+Open the invite link it prints, create your account and your first company. Then, optionally, add `PAPERCLIP_AUTH_DISABLE_SIGN_UP=true` to the variables to close public sign-ups.
+
+## 7. Sign in your agents
+
+Put `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` in the variables, or sign in with a subscription from `railway ssh`:
+
+```
+HOME=/paperclip gosu node claude
+```
+
+The login is saved on the volume.
+
+## 8. Check and connect
+
+```
+curl https://YOUR-ADDRESS/api/health
+```
+
+You want `"status":"ok"`, `"deploymentExposure":"public"` and `"bootstrapStatus":"ready"`. Then [connect Papercliped](/docs/hosting#connect-papercliped) and send *"Catch me up on my Paperclip."*
+
+## Updates and backups
+
+- **Update:** service → **Deployments → Redeploy** pulls the latest `latest` image. A service with a volume has a short downtime on each deploy, and runs in progress stop, so do it when agents are idle.
+- **Backups:** Railway volumes have backups in the volume's settings; turn on scheduled backups. If you use Railway Postgres, it has its own backups.
+
+## Troubleshooting
+
+- **Deploy fails its health check:** look at the deploy logs. Usually a missing `BETTER_AUTH_SECRET`, or `PAPERCLIP_PUBLIC_URL` not starting with `https://`.
+- **"This hostname is not allowed":** `PAPERCLIP_PUBLIC_URL` doesn't match the address you opened, or exposure isn't `public`.
+- **Everything reset after a deploy:** the volume isn't mounted at exactly `/paperclip`.
+- **Agents are killed or slow:** give the service more memory (2–4 GB).
+- More: [Troubleshooting](/docs/troubleshooting).

package/site/docs/host-render.md

@@ -0,0 +1,79 @@
+# Host Paperclip on Render
+
+Render runs the official Paperclip image as a web service with a persistent disk and a free `https://` address.
+
+**You'll end up with:** Paperclip at `https://<name>.onrender.com` (or your own domain), its data on a Render disk, connected to Papercliped.
+
+**Time:** about 15 minutes. **Cost:** Paperclip needs at least 2 GB of memory, which is Render's **Standard** instance (about $25 a month), plus the disk ($0.25 per GB a month; 10 GB is plenty to start). Render's free instances **sleep and can't have a disk**, and the 512 MB Starter instance is too small, so neither works for Paperclip. Check Render's pricing page for current numbers.
+
+## Before you start
+
+- A Render account with a payment method.
+- Two random secrets. Make each with `openssl rand -hex 32`, or have your password manager generate a 64-character password of letters and numbers.
+
+## 1. Create the web service
+
+1. **New → Web Service → Existing Image** (deploy an existing image from a registry).
+2. Image URL: `ghcr.io/paperclipai/paperclip:latest`.
+3. Pick a region near you and the **Standard** instance type (2 GB) or larger.
+
+## 2. Add the settings
+
+Under **Environment Variables**, add:
+
+| Key | Value |
+| --- | --- |
+| `PAPERCLIP_DEPLOYMENT_MODE` | `authenticated` |
+| `PAPERCLIP_DEPLOYMENT_EXPOSURE` | `public` |
+| `PAPERCLIP_PUBLIC_URL` | `https://YOUR-SERVICE.onrender.com` (you'll see the exact name after creating it; update this then) |
+| `BETTER_AUTH_SECRET` | your first secret |
+| `PAPERCLIP_TOOL_ACTION_SIGNING_SECRET` | your second secret |
+| `PORT` | `3100` |
+| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | optional, for your agents |
+
+## 3. Add the disk and health check
+
+Under **Advanced**:
+
+- **Add Disk:** mount path **`/paperclip`**, size 10 GB. This is where Paperclip keeps its database, secrets key, uploads, workspaces and agent logins.
+- **Health Check Path:** `/api/health`.
+
+Create the service. When it's live, check that `PAPERCLIP_PUBLIC_URL` matches the address Render shows at the top of the page exactly; if not, fix it (Render redeploys).
+
+**Your own domain:** **Settings → Custom Domains → Add**, create the DNS record Render shows, and change `PAPERCLIP_PUBLIC_URL` to the new address.
+
+**Optional managed database:** create a Render Postgres (a paid one; the free one is deleted after 30 days) and set `DATABASE_URL` to its **Internal** URL. Without it Paperclip uses its built-in Postgres on the disk.
+
+## 4. Create your account
+
+Open the service's **Shell** tab and run:
+
+```
+HOME=/paperclip gosu node npx --yes paperclipai auth bootstrap-ceo --data-dir /paperclip --base-url https://YOUR-SERVICE.onrender.com
+```
+
+Open the invite link it prints, create your account and your first company. Optionally, add `PAPERCLIP_AUTH_DISABLE_SIGN_UP=true` afterwards to close public sign-ups.
+
+## 5. Sign in your agents
+
+Add `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or sign in with a subscription from the Shell tab (`HOME=/paperclip gosu node claude`). The login is saved on the disk.
+
+## 6. Check and connect
+
+```
+curl https://YOUR-SERVICE.onrender.com/api/health
+```
+
+You want `"status":"ok"`, `"deploymentExposure":"public"` and `"bootstrapStatus":"ready"`. Then [connect Papercliped](/docs/hosting#connect-papercliped) and send *"Catch me up on my Paperclip."*
+
+## Updates and backups
+
+- **Update:** **Manual Deploy → Deploy latest reference** pulls the newest `latest` image. A service with a disk can't do zero-downtime deploys: the old instance stops first, so runs in progress end. Update when agents are idle.
+- **Backups:** Render takes daily snapshots of disks; you can restore them from the disk's settings. Keep your own copy too for anything important.
+
+## Troubleshooting
+
+- **Deploy fails:** read the logs. Usually a missing `BETTER_AUTH_SECRET`, or a public URL without `https://`.
+- **"This hostname is not allowed":** `PAPERCLIP_PUBLIC_URL` doesn't match the address you're opening.
+- **Data gone after a deploy:** the disk isn't mounted at exactly `/paperclip`.
+- More: [Troubleshooting](/docs/troubleshooting).

package/site/docs/host-vps.md

@@ -0,0 +1,202 @@
+# Host Paperclip on a VPS with Docker
+
+A small rented server running the official Paperclip image, with Caddy in front for the `https://` certificate. This is the best value for a Paperclip that's on all the time, and every step is copy and paste.
+
+**You'll end up with:** Paperclip at `https://paperclip.yourdomain.com`, restarting by itself, with its data on the server's disk, connected to Papercliped.
+
+**Time:** about 30 minutes. **Cost:** the server (about €5–12 a month) and a domain.
+
+## Before you start
+
+- **A domain** you can add DNS records to (any registrar works). You'll use a subdomain like `paperclip.yourdomain.com`.
+- **An SSH key.** On macOS, Linux and Windows 10+, run `ssh-keygen` in a terminal and press Enter at each question if you don't have one.
+
+## 1. Rent the server
+
+Pick **Ubuntu 24.04**, at least **2 GB of memory (4 GB recommended)**, and add your SSH key when asked.
+
+| Provider | A plan that fits (Oct 2026, approx.) | Notes |
+| --- | --- | --- |
+| Hetzner | CX23 (2 vCPU, 4 GB), about €5.50 | Best value; EU and US locations |
+| DigitalOcean | Basic Droplet 2 GB, about $12 | Choose a *Droplet*, not App Platform |
+| Linode (Akamai) | Shared 2 GB, about $12 | |
+| Oracle Cloud Always Free | Ampere A1, $0 | Free but fiddly: see [Oracle notes](#oracle-cloud-free-tier) |
+
+Note the server's **public IPv4 address**.
+
+## 2. Point your domain at it
+
+At your DNS provider, add an **A record**: name `paperclip`, value the server's IP. (If your DNS is on Cloudflare, set it to **DNS only**, the grey cloud, so Caddy can get its certificate.) It usually works within a few minutes.
+
+## 3. Install Docker and open the firewall
+
+Connect to the server (`ssh root@YOUR_IP`), then:
+
+```
+curl -fsSL https://get.docker.com | sh
+ufw allow 22/tcp && ufw allow 80/tcp && ufw allow 443/tcp && ufw allow 443/udp
+ufw --force enable
+```
+
+## 4. Create the settings
+
+Replace `paperclip.yourdomain.com` with your address:
+
+```
+mkdir -p ~/paperclip && cd ~/paperclip
+cat > .env <<EOF
+DOMAIN=paperclip.yourdomain.com
+BETTER_AUTH_SECRET=$(openssl rand -hex 32)
+PAPERCLIP_TOOL_ACTION_SIGNING_SECRET=$(openssl rand -hex 32)
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+EOF
+chmod 600 .env
+```
+
+Leave the two API keys empty if you'll sign your agents in with a subscription instead (step 8).
+
+## 5. Create the Docker Compose file
+
+```
+cat > docker-compose.yml <<'EOF'
+services:
+  paperclip:
+    image: ghcr.io/paperclipai/paperclip:latest
+    container_name: paperclip
+    restart: unless-stopped
+    pids_limit: 2048
+    environment:
+      PAPERCLIP_DEPLOYMENT_MODE: authenticated
+      PAPERCLIP_DEPLOYMENT_EXPOSURE: public
+      PAPERCLIP_PUBLIC_URL: https://${DOMAIN}
+      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
+      PAPERCLIP_TOOL_ACTION_SIGNING_SECRET: ${PAPERCLIP_TOOL_ACTION_SIGNING_SECRET}
+      TRUST_PROXY: uniquelocal
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+      OPENAI_API_KEY: ${OPENAI_API_KEY}
+    volumes:
+      - paperclip-data:/paperclip
+  caddy:
+    image: caddy:2
+    restart: unless-stopped
+    ports: ["80:80", "443:443", "443:443/udp"]
+    environment:
+      DOMAIN: ${DOMAIN}
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy-data:/data
+      - caddy-config:/config
+    depends_on: [paperclip]
+volumes:
+  paperclip-data:
+  caddy-data:
+  caddy-config:
+EOF
+```
+
+What this does: runs the official image (no building), keeps everything Paperclip stores in the `paperclip-data` volume, and only Caddy is reachable from the internet. Paperclip uses its built-in Postgres on that volume.
+
+## 6. Create the Caddy file
+
+```
+cat > Caddyfile <<'EOF'
+{$DOMAIN} {
+    reverse_proxy paperclip:3100
+}
+EOF
+```
+
+Caddy gets and renews the certificate by itself and passes Paperclip's live updates (WebSockets) through.
+
+## 7. Start it and create your account
+
+```
+docker compose up -d
+docker compose logs -f paperclip
+```
+
+Wait until the log says the server is listening (press Ctrl+C to stop watching; Paperclip keeps running). Then create the one-time invite for your admin account:
+
+```
+docker compose exec -u node paperclip npx --yes paperclipai auth bootstrap-ceo --data-dir /paperclip --base-url https://paperclip.yourdomain.com
+```
+
+Open the link it prints, create your account, and set up your first company.
+
+Optional, once you have your account: add `PAPERCLIP_AUTH_DISABLE_SIGN_UP: "true"` under `environment:` and run `docker compose up -d` to close public sign-ups.
+
+## 8. Sign in your agents
+
+Either put `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` in `.env` and run `docker compose up -d`, or sign in with your subscription inside the container:
+
+```
+docker compose exec -it -u node paperclip claude
+docker compose exec -it -u node paperclip codex
+```
+
+Logins are saved in the `paperclip-data` volume, so they survive restarts and updates.
+
+## 9. Check and connect
+
+```
+curl https://paperclip.yourdomain.com/api/health
+```
+
+You want `"status":"ok"`, `"deploymentExposure":"public"` and `"bootstrapStatus":"ready"`. Then [connect Papercliped](/docs/hosting#connect-papercliped) and send *"Catch me up on my Paperclip."*
+
+## Updates
+
+When your agents are idle (an update restarts Paperclip and stops runs in progress):
+
+```
+cd ~/paperclip && docker compose pull && docker compose up -d
+```
+
+To pin a version instead of `latest`, use a tag like `ghcr.io/paperclipai/paperclip:2026.1005.0` and read Paperclip's release notes before changing it.
+
+## Backups
+
+Everything is in the `paperclip-data` volume. The safest copy is with Paperclip stopped:
+
+```
+cd ~/paperclip && docker compose stop paperclip
+docker run --rm -v paperclip_paperclip-data:/data -v "$PWD":/backup alpine tar czf /backup/paperclip-$(date +%F).tgz -C /data .
+docker compose start paperclip
+```
+
+Copy the `.tgz` somewhere off the server. Many providers also sell automatic server snapshots for a small fee.
+
+## Use a separate Postgres (optional)
+
+For bigger setups, add a Postgres service and point Paperclip at it:
+
+```
+  db:
+    image: postgres:17-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: paperclip
+      POSTGRES_PASSWORD: change-me-long-random
+      POSTGRES_DB: paperclip
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+```
+
+Then add `DATABASE_URL: postgres://paperclip:change-me-long-random@db:5432/paperclip` to Paperclip's `environment:` and `pgdata:` under `volumes:`. Do this on a fresh install; moving existing data needs a database export and import.
+
+## Oracle Cloud free tier
+
+Oracle's Always Free Ampere A1 servers are free but take extra steps:
+
+- Open ports 80 and 443 in **two places**: the VCN's security list in the Oracle console, **and** the server's own firewall (Oracle's Ubuntu images ship strict `iptables` rules; allow 80 and 443 there or replace them with `ufw`).
+- A1 servers are ARM; the Paperclip image supports ARM, so nothing else changes.
+- Free capacity is often "out of host capacity" in popular regions, and Oracle can reclaim idle free servers. Fine for trying things, risky for anything you rely on.
+
+## Troubleshooting
+
+- **Caddy can't get a certificate:** the A record isn't pointing at the server yet, port 80 or 443 is closed, or Cloudflare's orange-cloud proxy is on. Check with `docker compose logs caddy`.
+- **"This hostname is not allowed":** `PAPERCLIP_DEPLOYMENT_EXPOSURE` isn't `public`, or `PAPERCLIP_PUBLIC_URL` doesn't match the address you're using.
+- **The container keeps restarting:** run `docker compose logs paperclip`. A missing `BETTER_AUTH_SECRET` or a public URL that isn't `https://` stops it at startup.
+- **Agents fail straight away:** they have no API key or login (step 8).
+- More: [Troubleshooting](/docs/troubleshooting).

package/site/docs/hosting.md

@@ -0,0 +1,105 @@
+# Host your Paperclip
+
+Papercliped connects your AI app to **your** Paperclip over the internet, so your Paperclip needs a public `https://` address. This section takes you from nothing to a running Paperclip with a public address, connected to Papercliped, with one complete guide per hosting option.
+
+Already have Paperclip running at a public `https://` address? Skip to [Connect Papercliped](#connect-papercliped).
+
+## Pick where to run it
+
+| Option | Cost per month (Oct 2026, approx.) | Effort | Best for | Guide |
+| --- | --- | --- | --- | --- |
+| **Your own computer + a tunnel** | Free (plus a domain, if you want one) | Medium | Trying it out; a computer that's always on | [At home, with a tunnel](/docs/connect-your-paperclip) |
+| **A VPS with Docker** (Hetzner, DigitalOcean, Linode…) | about €5–12 | Medium | Best value for daily use, full control | [VPS with Docker](/docs/host-vps) |
+| **Railway** | about $10–25 (usage-based) | Easy | The fewest steps, no server to look after | [Railway](/docs/host-railway) |
+| **Render** | about $25+ (2 GB plan) plus disk | Easy | A dashboard you already know | [Render](/docs/host-render) |
+| **Fly.io** | about $11–22 plus volume | Medium | Command-line people, pick your region | [Fly.io](/docs/host-fly) |
+| **Coolify** on a VPS | your VPS (8 GB recommended) | Easy–medium | A point-and-click panel on your own server | [Coolify](/docs/host-coolify) |
+
+Prices change; check the provider's pricing page before you sign up.
+
+**Not recommended:** free tiers that **sleep** (Render free, Railway's free plan) or hosts with **no persistent disk** (DigitalOcean App Platform). Paperclip keeps its database, secrets key, uploads, agent workspaces and agent logins on disk, and a sleeping server stops your agents mid-task. Use a DigitalOcean *Droplet* with the [VPS guide](/docs/host-vps) instead.
+
+**Not sure?** Start at home with a tunnel to try everything for free. When you want it running all the time, move to a VPS (cheapest) or Railway (easiest).
+
+## What every option needs
+
+Every guide sets these up. If you're doing something we don't cover, this is the checklist.
+
+1. **Paperclip in authenticated, public mode.** Paperclip has two modes: `local_trusted` (no login, only on your own computer) and `authenticated` (people sign in). An internet-facing Paperclip must be `authenticated` with `public` exposure. Never put a `local_trusted` Paperclip behind a public address.
+2. **Its public address set explicitly.** Paperclip builds sign-in links and checks hostnames from it.
+3. **Two long random secrets.** One for sign-ins, one for signing tool-action approvals.
+4. **A persistent disk** at Paperclip's data folder (`/paperclip` in the Docker image, `~/.paperclip` otherwise).
+5. **At least 2 GB of memory, 4 GB if you run several agents.** Agents run as programs inside the same machine.
+6. **Always on.** A restart or redeploy stops any agent run in progress, so avoid hosts that sleep, and update when your agents are idle.
+7. **Nothing blocking `/api/*`.** No login wall, bot challenge or "under attack" mode in front of Paperclip's API, or Papercliped can't reach it.
+
+### The settings
+
+| Setting | Value | Why |
+| --- | --- | --- |
+| `PAPERCLIP_DEPLOYMENT_MODE` | `authenticated` | People sign in (the Docker image's default) |
+| `PAPERCLIP_DEPLOYMENT_EXPOSURE` | `public` | Internet-facing. The Docker image defaults to `private`, which refuses unknown hostnames |
+| `PAPERCLIP_PUBLIC_URL` | `https://paperclip.example.com` | Your public address, exactly as people will type it |
+| `BETTER_AUTH_SECRET` | 64 random hex characters | Signs sign-in sessions. Required |
+| `PAPERCLIP_TOOL_ACTION_SIGNING_SECRET` | 64 random hex characters | Signs tool-action approvals |
+| `PORT` | `3100` | Paperclip's port (the image's default; some hosts need it set) |
+| `DATABASE_URL` | optional | Leave unset to use Paperclip's built-in Postgres on the disk, or point it at a managed Postgres |
+| `TRUST_PROXY` | optional | Tells Paperclip which proxy in front of it to believe about the visitor's address (`uniquelocal` behind Caddy in Docker). Leave unset if unsure |
+| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | optional | Keys for the agents that use Claude Code or Codex. You can sign in inside the server instead (see each guide) |
+
+Make a secret with:
+
+```
+openssl rand -hex 32
+```
+
+No `openssl`? Any password manager can generate a 64-character random password; use letters and numbers only.
+
+### Your first account
+
+In public mode, Paperclip doesn't show a "claim this instance" button (anyone on the internet could press it). Instead you run one command on the server, which prints a **one-time invite link** for the first admin:
+
+```
+npx --yes paperclipai auth bootstrap-ceo --data-dir /paperclip --base-url https://paperclip.example.com
+```
+
+Each guide shows exactly where to run it. Open the link, create your account, and you're the admin. Once you have your account, you can close public sign-ups by setting `PAPERCLIP_AUTH_DISABLE_SIGN_UP=true` and restarting; invite teammates from inside Paperclip.
+
+### Your agents' keys
+
+The official Paperclip image already includes the Claude Code, Codex, OpenCode and Gemini command-line tools, plus git and the GitHub CLI. Your agents need one of:
+
+- **An API key** as a setting: `ANTHROPIC_API_KEY` for Claude Code agents, `OPENAI_API_KEY` for Codex agents.
+- **Your subscription login**, done once inside the server (for example `claude` or `codex`, then follow the sign-in). The login is saved on the persistent disk, so it survives restarts.
+
+## Check it works
+
+From any computer (your phone on mobile data is a good test):
+
+```
+curl https://paperclip.example.com/api/health
+```
+
+On Windows PowerShell use `curl.exe`. A healthy answer is JSON that includes:
+
+```
+"status":"ok", "deploymentMode":"authenticated", "deploymentExposure":"public", "bootstrapStatus":"ready"
+```
+
+`"bootstrapStatus":"bootstrap_pending"` means nobody has created the first account yet (see [Your first account](#your-first-account)).
+
+## Connect Papercliped
+
+1. Add the connector in your AI app. In Claude: **Settings → Connectors → Add custom connector**, address `{{MCP}}/mcp`. Other apps: [Any AI app](/docs/other-ai-apps), [ChatGPT](/docs/chatgpt).
+2. On the Papercliped page choose **Connect your Paperclip** and enter your public address (just `https://paperclip.example.com`, no path).
+3. Approve the request in your Paperclip (you'll be asked to sign in), pick a username, save the secret key you're shown once, and choose **Read only** or **Full control**. Details: [Create your account](/docs/signup).
+4. Leave **Also install the Papercliped plugin** ticked to manage your connections from inside Paperclip ([Paperclip plugin](/docs/paperclip-plugin)).
+5. Send your first prompt: *"Catch me up on my Paperclip."* Then try more from the [prompt gallery](/docs/prompts).
+
+## Keep it safe
+
+- Use long random secrets and keep them out of chats, screenshots and Git.
+- Keep Paperclip up to date, and update when agents are idle.
+- Back up the data disk (each guide says how).
+- Expose only Paperclip, nothing else on the machine.
+- You can cut Papercliped's access at any time: disconnect apps in the [Paperclip plugin](/docs/paperclip-plugin), or revoke the key in Paperclip.