papercliped 2.2.1 → 2.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Run your Paperclip from Claude: control agents, sync with them and get reports, at the access level you choose.",
   "author": {
     "name": "KpnWorld"

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## v2.3.0 — host your Paperclip anywhere, and a prompt gallery
+
+- **Host your Paperclip: a step-by-step guide for every option.** A new docs section takes you from nothing to a running Paperclip with a public `https://` address, connected to Papercliped and answering your first prompt. It covers your own computer with a free tunnel (Cloudflare Tunnel, Tailscale Funnel, ngrok), a VPS with Docker and Caddy (Hetzner, DigitalOcean, Linode, Oracle's free tier), Railway, Render, Fly.io and Coolify, with a comparison of cost and effort. Every guide uses the official Paperclip image and the settings current Paperclip needs: authenticated mode with public exposure, your public URL, the two secrets, a persistent disk at `/paperclip`, creating the first admin with `paperclipai auth bootstrap-ceo`, and signing in your agents with API keys or a subscription. They also cover updates and backups. Hosts that sleep or have no disk are flagged as unsuitable.
+- **Prompt gallery.** More than 40 ready-to-copy prompts at papercliped.co/prompts and in the docs (Guides → Prompt gallery). Run Paperclip in plain words instead of clicking through the dashboard: catch up in the morning, hand out issues, wake an agent and follow its run, answer approvals, set budgets and get reports. Each prompt shows the access level it needs and the tools it uses. You can search and filter by category or level.
+- **Docs fixes:** the setup guide now uses Paperclip's real setting names and the current health check fields. Troubleshooting covers "hostname not allowed", connections that stop after Paperclip's 30-day key expiry (reconnect to fix), and agents stopping on restarts. The FAQ explains how Papercliped relates to Paperclip's new built-in MCP endpoint. Numbered steps with code blocks, and quotes, now render properly in the docs.
+
 ## v2.2.1 — the Papercliped plugin now installs in Paperclip
 
 - **Fixed: the Papercliped plugin could not be installed in Paperclip.** Paperclip rejected it with a bare "400" because the sidebar entry declared a page route, which Paperclip only allows on pages. Installing it, automatically while connecting or by hand from Settings → Plugins, now works. The plugin’s tests now run Paperclip’s own manifest check so this can’t come back. If you ticked the box while connecting on 2.2.0, nothing was installed: connect again, or install it from Settings → Plugins.

package/README.md

@@ -12,7 +12,7 @@ Free and open source. Website: [papercliped.co](https://papercliped.co) · Docs:
 
 ## Add it to your AI app
 
-You need a Paperclip with a public `https` address ([no domain? see this](https://docs.papercliped.co/connect-your-paperclip)). The first time you connect, you approve the request inside your own Paperclip, pick a username, save the secret key you're shown once, and choose **Read only** or **Full control**.
+You need a Paperclip with a public `https` address. Don't have one yet? [Host your Paperclip](https://docs.papercliped.co/hosting) has step-by-step guides for your own computer (free tunnel), a VPS, Railway, Render, Fly.io and Coolify. The first time you connect, you approve the request inside your own Paperclip, pick a username, save the secret key you're shown once, and choose **Read only** or **Full control**.
 
 The connector address for every app is:
 
@@ -80,9 +80,13 @@ Add `--env PAPERCLIP_READ_ONLY=1` for reports and sync only.
 
 ## What you can ask
 
-- "What are my agents working on?" · "Which agents are over budget?"
-- "Pause the Web Engineer." · "Wake the CEO and assign it the onboarding issue."
-- "Approve the hire request." · "Weekly cost report, please."
+Talk to your AI app instead of clicking through the dashboard:
+
+- "Catch me up on my Paperclip." · "Which agents are over budget?"
+- "Give the Web Engineer an issue to fix the signup page, and wake them." · "Wake the CEO, wait until they finish, then summarise."
+- "Approve the hire request." · "Weekly report, please."
+
+More than 40 ready-to-copy prompts: [prompt gallery](https://papercliped.co/prompts).
 
 There are 30 tools ([full list](https://docs.papercliped.co/tools)). **Read only** can look at agents, issues, goals, costs and reports. **Full control** can use every tool. The AI asks before anything that can't be undone, and you can change the level or disconnect at any time.
 

package/dist/site/markdown.js

@@ -55,21 +55,42 @@ export function renderMarkdown(md) {
             out.push(`<div class="tw"><table><thead><tr>${head.map((c) => `<th>${inline(c)}</th>`).join("")}</tr></thead><tbody>${rows.map((r) => `<tr>${r.map((c) => `<td>${inline(c)}</td>`).join("")}</tr>`).join("")}</tbody></table></div>`);
             continue;
         }
+        if (/^>/.test(line)) {
+            const buf = [];
+            while (i < lines.length && /^>/.test(lines[i]))
+                buf.push(lines[i++].replace(/^>\s?/, ""));
+            out.push(`<blockquote>${renderMarkdown(buf.join("\n"))}</blockquote>`);
+            continue;
+        }
         const ul = /^[-*]\s+/.test(line), ol = /^\d+\.\s+/.test(line);
         if (ul || ol) {
             const items = [];
             const re = ul ? /^[-*]\s+(.*)$/ : /^\d+\.\s+(.*)$/;
             while (i < lines.length && re.test(lines[i])) {
-                let t = re.exec(lines[i++])[1];
-                while (i < lines.length && /^\s+\S/.test(lines[i]) && !re.test(lines[i]))
-                    t += " " + lines[i++].trim();
-                items.push(`<li>${inline(t)}</li>`);
+                const body = [re.exec(lines[i++])[1]];
+                // An item continues on indented lines, including fenced code and blank lines followed by more indented content.
+                while (i < lines.length && !re.test(lines[i])) {
+                    if (/^\s+\S/.test(lines[i]))
+                        body.push(lines[i++]);
+                    else if (!lines[i].trim() && /^\s+\S/.test(lines[i + 1] ?? "") && !re.test(lines[i + 1] ?? ""))
+                        body.push(lines[i++]);
+                    else
+                        break;
+                }
+                const rich = body.some((l) => /^\s*```/.test(l) || !l.trim());
+                if (!rich)
+                    items.push(`<li>${inline(body.map((l) => l.trim()).join(" "))}</li>`);
+                else {
+                    const rest = body.slice(1);
+                    const pad = Math.min(...rest.filter((l) => l.trim()).map((l) => /^\s*/.exec(l)[0].length));
+                    items.push(`<li>${renderMarkdown([body[0], ...rest.map((l) => l.slice(Math.min(pad, /^\s*/.exec(l)[0].length)))].join("\n"))}</li>`);
+                }
             }
             out.push(ul ? `<ul>${items.join("")}</ul>` : `<ol>${items.join("")}</ol>`);
             continue;
         }
         const para = [];
-        while (i < lines.length && lines[i].trim() && !/^(#{1,3}\s|```|[-*]\s|\d+\.\s)/.test(lines[i]) && !/^\|.*\|\s*$/.test(lines[i]))
+        while (i < lines.length && lines[i].trim() && !/^(#{1,3}\s|```|[-*]\s|\d+\.\s|>)/.test(lines[i]) && !/^\|.*\|\s*$/.test(lines[i]))
             para.push(lines[i++].trim());
         out.push(`<p>${inline(para.join(" "))}</p>`);
     }

package/dist/site/site.js

@@ -9,9 +9,16 @@ const NAV = [
     { slug: "getting-started", title: "Getting started" },
     { slug: "what-is-papercliped", title: "What is Papercliped?" },
     { slug: "signup", title: "Create your account" },
-    { slug: "connect-your-paperclip", title: "Set up your Paperclip" },
+    { slug: "hosting", title: "Host your Paperclip" },
+    { slug: "connect-your-paperclip", title: "At home, with a tunnel" },
+    { slug: "host-vps", title: "VPS with Docker" },
+    { slug: "host-railway", title: "Railway" },
+    { slug: "host-render", title: "Render" },
+    { slug: "host-fly", title: "Fly.io" },
+    { slug: "host-coolify", title: "Coolify" },
     { slug: "other-ai-apps", title: "Any AI app (MCP)" },
     { slug: "chatgpt", title: "ChatGPT setup" },
+    { slug: "prompts", title: "Prompt gallery" },
     { slug: "permissions", title: "Permissions" },
     { slug: "manage", title: "Manage connections" },
     { slug: "paperclip-plugin", title: "Paperclip plugin" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Papercliped — connect Claude, ChatGPT and any MCP app to your Paperclip: control agents, sync, report. MCP server + hosted multi-tenant OAuth bridge + public stats API.",
   "license": "MIT",
   "type": "module",

package/site/docs/connect-your-paperclip.md

@@ -1,120 +1,166 @@
-# Set up your Paperclip for Papercliped
+# At home, with a tunnel
 
-Papercliped talks to **your** Paperclip over the internet, so your Paperclip needs a public address. This guide gets you one, step by step, whether you already own a domain or not.
+Run Paperclip on your own computer and give it a public `https://` address with a free tunnel. You don't open any ports on your router. This is the cheapest way to start, and a good way to try Papercliped before you rent a server.
 
-You don't need to open any ports on your router for any option below.
+**You'll end up with:** Paperclip on your computer, reachable at a public address like `https://paperclip.yourdomain.com` or `https://my-pc.my-tailnet.ts.net`, connected to Papercliped.
 
-## What Papercliped needs from your Paperclip
-- **A public `https://` address on port 443** that answers over the internet. Private, LAN, `localhost` and plain `http://` addresses are refused on purpose.
-- **Paperclip in authenticated mode and public exposure.** You can check from any computer:
-  ```
-  curl https://your-address/api/health
-  ```
-  A healthy answer is JSON that includes `"status":"ok"`, `"deploymentMode":"authenticated"` and `"deploymentExposure":"public"`. (On Windows PowerShell, `curl.exe https://your-address/api/health` works the same way.)
-- **No login wall or bot challenge in front of `/api/*`.** If you put something like Cloudflare Access, "Under Attack" mode or a managed challenge in front of Paperclip, it must skip `/api/*`, or Papercliped will be blocked.
-- **Paperclip must accept the new hostname.** Paperclip can reject hostnames it doesn't know, and public mode needs its public URL set. Paperclip's own settings for this include `PAPERCLIP_PUBLIC_URL` and `PAPERCLIP_ALLOWED_HOSTNAMES`; the exact steps are in Paperclip's deployment docs (search "Paperclip deployment modes" on docs.paperclip.ing). Check them there rather than guessing.
+**Good to know:** while your computer sleeps or is off, your agents and your AI app's connection stop. For a Paperclip that's always on, use a [VPS or a hosting platform](/docs/hosting).
 
-Paperclip listens on port `3100` by default, which the examples below use. If yours is different, use your port.
+## 1. Choose a tunnel
 
-## Path A: you own a domain (recommended)
-This gives you a stable address like `https://paperclip.yourdomain.com` that survives restarts. The tunnel and DNS are free on Cloudflare's free plan. The domain itself isn't: there is no free `.com`. (Cloudflare Registrar sells domains at wholesale cost, so it's one cheap option if you need to buy one.)
+| Tunnel | Your address | Stays the same? | Needs | Good for |
+| --- | --- | --- | --- | --- |
+| **Cloudflare Tunnel** | `https://paperclip.yourdomain.com` | Yes | A domain on Cloudflare (free plan) | Daily use (recommended) |
+| **Tailscale Funnel** | `https://<computer>.<tailnet>.ts.net` | Yes | A free Tailscale account | Daily use without a domain |
+| **ngrok** | one free `*.ngrok-free.app` address | Yes | A free ngrok account | Daily use without a domain |
+| **Cloudflare quick tunnel** | random `*.trycloudflare.com` | **No, changes every restart** | Nothing | Trying it for an afternoon |
 
-1. **Put your domain on Cloudflare.** Create a free Cloudflare account, add your domain, and switch its nameservers to the two Cloudflare gives you (done at the company where you bought the domain). Wait until Cloudflare shows the domain as active.
-2. **Install `cloudflared`** on the machine that runs Paperclip. Find the installer for Windows, macOS or Linux on Cloudflare's downloads page (search "cloudflared downloads").
-3. **Log in.** This opens a browser so you can pick your domain:
-   ```
-   cloudflared tunnel login
-   ```
-4. **Create the tunnel.** Pick any name:
-   ```
-   cloudflared tunnel create papercliped-paperclip
-   ```
-   It prints a tunnel ID (a UUID) and saves a credentials file in your `.cloudflared` folder. Keep that file private.
-5. **Write the config.** In your `.cloudflared` folder (`~/.cloudflared` on macOS/Linux, `%USERPROFILE%\.cloudflared` on Windows) create `config.yml`:
-   ```
-   tunnel: <TUNNEL-ID>
-   credentials-file: <PATH-TO-THE-CREDENTIALS-FILE>.json
-   ingress:
-     - hostname: paperclip.yourdomain.com
-       service: http://localhost:3100
-     - service: http_status:404
-   ```
-   The last rule is required: it answers 404 for anything else.
-6. **Point the name at the tunnel:**
-   ```
-   cloudflared tunnel route dns papercliped-paperclip paperclip.yourdomain.com
-   ```
-7. **Run it.** To try it first:
-   ```
-   cloudflared tunnel run papercliped-paperclip
-   ```
-   To keep it running (starts with your computer), install it as a service:
-   - **macOS:** `cloudflared service install` (runs when you log in) or `sudo cloudflared service install` (runs at boot).
-   - **Linux:** `cloudflared service install` (with `sudo` if needed).
-   - **Windows:** run `cloudflared.exe service install` from an Administrator PowerShell. A Windows service may not read the config from your user folder; check Cloudflare's "Run as a service on Windows" page for where it expects `config.yml`.
-8. **Check it** from any computer:
-   ```
-   curl https://paperclip.yourdomain.com/api/health
-   ```
-   You should see the JSON described above.
+Pick one and **work out your address first**: Paperclip needs to know it during setup (step 2). The tunnel sections below show how to get it.
+
+## 2. Install Paperclip in public mode
+
+You need **Node.js 24.11 or newer** (check with `node -v`; get it from nodejs.org).
+
+```
+npx paperclipai onboard
+```
+
+When it asks:
+
+- **Deployment mode:** `authenticated` (people sign in).
+- **Exposure:** `public`.
+- **Public URL:** your tunnel address from step 1, for example `https://paperclip.yourdomain.com` (with `https://`, no slash at the end).
+- **Bind:** `loopback`. The tunnel connects from your own computer, so Paperclip doesn't need to listen on your network.
+
+These choices are the same as the settings `PAPERCLIP_DEPLOYMENT_MODE=authenticated`, `PAPERCLIP_DEPLOYMENT_EXPOSURE=public` and `PAPERCLIP_PUBLIC_URL`, which you can also set as environment variables. Onboarding creates the secrets Paperclip needs and saves them in `~/.paperclip/instances/default/.env`. Start Paperclip with:
+
+```
+npx paperclipai run
+```
+
+It listens on port **3100**. (If something else already uses 3100, Paperclip quietly picks another port and prints it; use that port in the tunnel instead.)
 
-**If your computer sleeps or turns off,** the tunnel goes down and your connected AI apps stop working until it's back. Turn off sleep on the machine, or run Paperclip on an always-on computer or server.
+**Already running Paperclip on this computer** in the default `local_trusted` mode (no login)? Change it with `npx paperclipai configure --section server`: choose `authenticated`, `public`, and your tunnel address. Never put a `local_trusted` Paperclip behind a public address: anyone who finds it could control it.
 
-## Path B: you don't have a domain yet
-All of these are free. They differ in how stable the address is.
+**Prefer Docker?** Use the Compose file from the [VPS guide](/docs/host-vps#5-create-the-docker-compose-file) without the `caddy` service, add `ports: ["127.0.0.1:3100:3100"]` to the Paperclip service, and set `DOMAIN` to your tunnel's hostname.
 
-| Option | Address | Stable? | Good for |
-| --- | --- | --- | --- |
-| Tailscale Funnel | `https://<machine>.<tailnet>.ts.net` | Yes | Daily use |
-| ngrok free plan | one free static `ngrok-free.app` / `ngrok-free.dev` domain | Yes | Daily use, with a caveat below |
-| Cloudflare quick tunnel | random `*.trycloudflare.com` | **No, changes every restart** | Trying Papercliped only |
+## 3. Start the tunnel
 
-### Tailscale Funnel (stable)
-Funnel makes a service on your computer reachable from the public internet at your tailnet's `ts.net` name.
-1. Create a free Tailscale account and install Tailscale on the machine that runs Paperclip.
-2. In the Tailscale admin console, turn on **HTTPS certificates** for your tailnet and allow Funnel. (Running the `tailscale funnel` command below walks you through enabling it and updates your tailnet policy for you.)
-3. Start Funnel for Paperclip's port:
+Follow the section for the tunnel you chose, then come back for step 4.
+
+### Cloudflare Tunnel (with your domain)
+
+Stable address on your own domain. The tunnel and DNS are free on Cloudflare's free plan; the domain itself isn't (Cloudflare Registrar sells them at cost).
+
+1. **Put your domain on Cloudflare:** create a free account, add your domain, and switch its nameservers to the two Cloudflare gives you (at the company where you bought the domain). Wait until Cloudflare shows it as active.
+2. In the Cloudflare dashboard, open **Zero Trust → Networks → Tunnels → Create a tunnel**, choose **Cloudflared**, and name it `paperclip`.
+3. Cloudflare shows an install command for Windows, macOS or Linux that includes a token, like `cloudflared service install eyJ…`. Run it on this computer. It installs `cloudflared` as a service that starts with the computer. (Keep the token private; it's the key to your tunnel.)
+4. Under **Public Hostname**, add: subdomain `paperclip`, your domain, service type **HTTP**, URL **`localhost:3100`**. Save.
+
+That's it: `https://paperclip.yourdomain.com` now reaches your Paperclip. Don't turn on Cloudflare Access, Bot Fight Mode or a WAF challenge for this hostname (or exempt `/api/*`), or Papercliped will be blocked.
+
+<details><summary>Prefer the command line?</summary>
+
+```
+cloudflared tunnel login
+cloudflared tunnel create paperclip
+cloudflared tunnel route dns paperclip paperclip.yourdomain.com
+```
+
+Create `config.yml` in your `.cloudflared` folder (`~/.cloudflared` on macOS and Linux):
+
+```
+tunnel: <TUNNEL-ID>
+credentials-file: <PATH-TO-THE-CREDENTIALS-FILE>.json
+ingress:
+  - hostname: paperclip.yourdomain.com
+    service: http://localhost:3100
+  - service: http_status:404
+```
+
+Try it with `cloudflared tunnel run paperclip`, then install it as a service with `cloudflared service install` (`sudo` on Linux and for start-at-boot on macOS). **On Windows** the service runs as SYSTEM, so it doesn't read your user folder: put `config.yml` and the credentials file in `C:\Windows\System32\config\systemprofile\.cloudflared\`, then run `cloudflared.exe service install` from an Administrator PowerShell. The dashboard method above avoids all of this.
+
+</details>
+
+### Tailscale Funnel (no domain)
+
+1. Create a free Tailscale account and install Tailscale on this computer.
+2. Run:
    ```
-   tailscale funnel 3100
+   tailscale funnel --bg 3100
    ```
-   It prints your public address, like `https://my-pc.my-tailnet.ts.net`. Funnel only serves on ports 443, 8443 and 10000; use the default 443 for Papercliped.
-4. Funnel traffic has bandwidth limits you can't change. That is fine for Papercliped's small requests, but check Tailscale's Funnel docs for the current rules on your plan.
+   The first time, it walks you through turning on HTTPS certificates and Funnel for your tailnet. It prints your address, like `https://my-pc.my-tailnet.ts.net`, and keeps running in the background.
+3. Funnel only serves on ports 443, 8443 and 10000; the command above uses 443, which is what Papercliped needs. Funnel addresses always end in `.ts.net` (no custom domains), and bandwidth is limited, which is fine for Papercliped's small requests.
 
-### ngrok free plan (stable address, one catch)
-1. Create a free ngrok account. Every account gets one free static "dev domain" (for example `your-name.ngrok-free.dev`); see it in the ngrok dashboard under Domains.
+Find your address any time with `tailscale funnel status`.
+
+### ngrok (no domain)
+
+1. Create a free ngrok account. Your account gets one free static address (under **Domains** in the ngrok dashboard), like `your-name.ngrok-free.app`. You can't choose it on the free plan.
 2. Install ngrok and add your authtoken (the dashboard shows the exact command).
-3. Run, with your own domain:
+3. Run, with your own address:
    ```
-   ngrok http --url=your-name.ngrok-free.dev 3100
+   ngrok http --url=your-name.ngrok-free.app 3100
    ```
-4. **The catch:** on the free plan ngrok shows a "visit site" warning page to browsers. Papercliped's requests come from a program, not a browser, but if the connection fails with a strange HTML page, this is the likely cause. Check ngrok's free-plan docs for the current behavior and any header that skips it.
+4. On the free plan ngrok shows a "You are about to visit…" page to **web browsers** the first time. Click **Visit Site** when you open Paperclip in your browser; requests from programs like Papercliped aren't affected. If a connection ever fails with an unexpected HTML page, this page is the likely cause.
+
+To keep ngrok running after you close the terminal, see ngrok's docs on running it as a service (`ngrok service install`).
 
 ### Cloudflare quick tunnel (trial only)
-No account, no domain:
+
+No account, no domain. Install `cloudflared`, then:
+
 ```
 cloudflared tunnel --url http://localhost:3100
 ```
-It prints a random `https://something.trycloudflare.com` address. **The address changes every time you restart it**, and when it changes your Papercliped connection stops working until you connect again with the new address. Quick tunnels are for trying Papercliped for an afternoon, not for daily use.
 
-## Connect to Papercliped
-1. Make sure `curl https://your-address/api/health` works (see above).
-2. Go to [Create your account]({{URL}}/docs/signup), add Papercliped as a connector in Claude, and choose **Connect your Paperclip**.
-3. Enter your public address (just the address, no path), then approve the request in your Paperclip.
+It prints a random `https://something.trycloudflare.com` address. Use that as the public URL in step 2 (`npx paperclipai configure --section server` if you already onboarded). **The address changes every time you restart it**, and then Papercliped can't reach your Paperclip until you set the new address in Paperclip and connect again. Quick tunnels are for testing only.
+
+## 4. Create your account
+
+In another terminal on the same computer:
+
+```
+npx paperclipai auth bootstrap-ceo --base-url https://your-address
+```
+
+It prints a one-time invite link. Open it, create your account and your first company. (If you switched an existing Paperclip from `local_trusted`, it may instead print a one-time **claim** link when it starts; either works.)
+
+## 5. Check it works
+
+From another network (your phone on mobile data is a good test):
+
+```
+curl https://your-address/api/health
+```
+
+(On Windows PowerShell use `curl.exe`.) You want JSON with `"status":"ok"`, `"deploymentMode":"authenticated"`, `"deploymentExposure":"public"` and `"bootstrapStatus":"ready"`.
+
+## 6. Connect Papercliped
+
+1. Add the connector in your AI app. In Claude: **Settings → Connectors → Add custom connector**, address `{{MCP}}/mcp`.
+2. Choose **Connect your Paperclip**, enter your public address (just the address, no path) and approve the request in your Paperclip.
+3. Pick a username, save the secret key you're shown once, and choose **Read only** or **Full control**. Every screen: [Create your account](/docs/signup).
+4. Send your first prompt: *"Catch me up on my Paperclip."* More in the [prompt gallery](/docs/prompts).
+
+## Keep it running
+
+- **Turn off sleep** on this computer, or your agents and connection stop whenever it sleeps.
+- **Start Paperclip with the computer.** The Cloudflare dashboard tunnel and Tailscale already do; for Paperclip itself, add `npx paperclipai run` to your login items (macOS), Task Scheduler (Windows) or a systemd service (Linux), or use the Docker setup, which restarts by itself.
+- **Update Paperclip** with `npx paperclipai@latest run` when your agents are idle.
 
 ## Keep it safe
-- **Expose only Paperclip.** Point the tunnel at Paperclip's port and nothing else on your computer.
+
+- **Expose only Paperclip.** Point the tunnel at port 3100 and nothing else on your computer.
+- **Never expose `local_trusted` mode.** Always `authenticated` + `public`.
 - **Keep Paperclip up to date.**
-- **Use a dedicated Paperclip user for the connection** if you can, so you can see and limit what it does.
-- **You can cut access any time:** revoke the Papercliped key in Paperclip, or disconnect apps in the [Paperclip plugin](/docs/paperclip-plugin).
-- **If the tunnel or your computer is off,** connected apps simply stop working until it's back. Nothing is lost.
+- **You can cut access any time:** disconnect apps in the [Paperclip plugin](/docs/paperclip-plugin), or revoke the key in Paperclip.
 
 ## Troubleshooting
-- **"Could not reach your Paperclip":** the tunnel isn't running, the DNS name hasn't spread yet (give a new name a few minutes), or the address isn't on port 443. Test with `curl https://your-address/api/health` from another network (for example, your phone's mobile data).
-- **"Private address" errors:** you entered a LAN address, `localhost`, or `http://`. Use the public `https://` address from your tunnel.
-- **A challenge or login page appears:** exempt `/api/*` from Cloudflare Access, "Under Attack" mode or any managed challenge.
-- **"Host not allowed" or a 4xx from Paperclip:** Paperclip doesn't know the new hostname. Set its public URL and allowed hostnames (see Paperclip's deployment docs, above) and restart it.
-- **Certificate warnings:** use the HTTPS address your tunnel provider gives you, not your own certificate on a raw IP. Tunnels handle certificates for you.
-- **Worked yesterday, not today:** the address changed (quick tunnels do this), the tunnel stopped, or the computer slept.
-
-## Not independently confirmed
-These came from vendor docs summarized through search, not read page by page. Check the vendor's current docs before relying on them: Windows service setup for `cloudflared`, Tailscale's current Funnel limits, ngrok's free-plan warning page behavior, and Paperclip's exact setting names for public URL and allowed hostnames.
+
+- **"Could not reach your Paperclip":** the tunnel or Paperclip isn't running, a new DNS name hasn't spread yet (give it a few minutes), or the address isn't on port 443. Test with `curl` from another network.
+- **"Private address" errors:** you entered a LAN address, `localhost` or `http://`. Use the public `https://` address from your tunnel.
+- **"This hostname is not allowed for this Paperclip instance":** Paperclip's public URL doesn't match the tunnel address, or exposure is still `private`. Fix it with `npx paperclipai configure --section server` and restart.
+- **A challenge or login page appears:** exempt `/api/*` from Cloudflare Access, Bot Fight Mode, "Under Attack" mode or any managed challenge.
+- **Worked yesterday, not today:** the computer slept, the tunnel stopped, or a quick tunnel's address changed.
+- More: [Troubleshooting](/docs/troubleshooting).

package/site/docs/faq.md

@@ -12,8 +12,17 @@ Only what it asks for through the tools, within your level. Issue and comment te
 ## What do you store?
 Your username, a hash of your secret key, your Paperclip's address, an encrypted Paperclip key, connection records and a 30-day activity log. Details in [Privacy](/privacy).
 
+## What can I ask it?
+Anything you'd otherwise click through Paperclip for: "Catch me up", "Give the Web Engineer this task", "Approve the hire", "Weekly cost report". Browse ready-to-copy prompts in the [prompt gallery](/docs/prompts).
+
+## Where should I host Paperclip?
+At home with a free tunnel to try it; a small VPS (best value) or Railway (easiest) to keep it on all the time. Compare every option in [Host your Paperclip](/docs/hosting).
+
+## Paperclip has its own MCP server now. Do I still need Papercliped?
+Newer Paperclip versions include an experimental, off-by-default MCP endpoint for connecting assistants straight to your instance. Use whichever suits you. Papercliped adds a hosted connector that works with older Paperclips too, ChatGPT GPT Actions, the two access levels enforced on every call, an audit log, ready-made status, cost and performance reports, and connection management in the Paperclip plugin.
+
 ## Can I use it without a public Paperclip?
-Yes: run it locally with `npx papercliped@latest`. The hosted bridge needs a public https address; see [Set up your Paperclip](/docs/connect-your-paperclip).
+Yes: run it locally with `npx papercliped@latest`. The hosted bridge needs a public https address; see [Host your Paperclip](/docs/hosting).
 
 ## Why does pausing an agent fail with 403?
 Pause, resume, wake and approve need a Paperclip **board** token, and a connection at **Full control**. Check your level in the [Paperclip plugin](/docs/paperclip-plugin).

package/site/docs/getting-started.md

@@ -3,7 +3,7 @@
 Papercliped connects Claude (and ChatGPT) to **your** Paperclip. You keep control: you choose how much the AI may do, and you can cut access at any time.
 
 ## What you need
-- A Paperclip that is reachable over the internet at an `https://` address (for example `https://workforce.example.com`). Private, local and `http://` addresses are refused on purpose. No public address yet? See [Set up your Paperclip](/docs/connect-your-paperclip).
+- A Paperclip that is reachable over the internet at an `https://` address (for example `https://workforce.example.com`). Private, local and `http://` addresses are refused on purpose. No public address yet? See [Host your Paperclip](/docs/hosting).
 - A Claude account that can add connectors, or Claude Code.
 
 ## Connect from Claude

package/site/docs/host-coolify.md

@@ -0,0 +1,78 @@
+# Host Paperclip with Coolify
+
+Coolify is a free, open-source control panel you install on your own server. It gives you a Railway-style dashboard (deploys, domains, certificates, logs, a terminal) on a VPS you pay for directly.
+
+**You'll end up with:** Coolify on your server, running Paperclip at `https://paperclip.yourdomain.com`, connected to Papercliped.
+
+**Time:** about 30 minutes. **Cost:** your server. Coolify itself needs about 2 GB of memory, Paperclip another 2–4 GB, so pick an **8 GB** server (for example Hetzner's 8 GB plans). Self-hosted Coolify is free; Coolify Cloud (they run the panel, you bring the server) is about $5 a month.
+
+## 1. Get a server and install Coolify
+
+1. Rent an Ubuntu 24.04 server with 8 GB of memory (see the provider table in [VPS with Docker](/docs/host-vps#1-rent-the-server)).
+2. Connect with `ssh root@YOUR_IP` and run Coolify's installer:
+   ```
+   curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash
+   ```
+3. Open `http://YOUR_IP:8000` and create your Coolify admin account straight away (the first person to open it becomes the admin).
+
+## 2. Point your domain at it
+
+At your DNS provider, add an **A record**: `paperclip` → your server's IP (on Cloudflare: **DNS only**, grey cloud).
+
+## 3. Create Paperclip
+
+1. In Coolify: **Projects → your project → New Resource → Docker Image**.
+2. Image: `ghcr.io/paperclipai/paperclip:latest`.
+3. **Ports Exposes:** `3100`.
+4. **Domains:** `https://paperclip.yourdomain.com`. Coolify gets the certificate for you.
+
+## 4. Add storage, health check and settings
+
+- **Persistent Storage → Add → Volume:** destination path **`/paperclip`**.
+- **Health check:** path `/api/health`, port `3100`.
+- **Environment Variables:** add
+
+```
+PAPERCLIP_DEPLOYMENT_MODE=authenticated
+PAPERCLIP_DEPLOYMENT_EXPOSURE=public
+PAPERCLIP_PUBLIC_URL=https://paperclip.yourdomain.com
+BETTER_AUTH_SECRET=YOUR-FIRST-SECRET
+PAPERCLIP_TOOL_ACTION_SIGNING_SECRET=YOUR-SECOND-SECRET
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+```
+
+Make each secret with `openssl rand -hex 32` (run it on the server). Then **Deploy**.
+
+Prefer Docker Compose? Choose **Docker Compose** as the resource type and paste the Paperclip service from the [VPS guide](/docs/host-vps#5-create-the-docker-compose-file) **without** the `caddy` service: Coolify's own proxy takes Caddy's place.
+
+## 5. Create your account
+
+Open the resource's **Terminal** tab and run:
+
+```
+HOME=/paperclip gosu node npx --yes paperclipai auth bootstrap-ceo --data-dir /paperclip --base-url https://paperclip.yourdomain.com
+```
+
+Open the invite link, create your account and your first company. Optionally add `PAPERCLIP_AUTH_DISABLE_SIGN_UP=true` and redeploy to close public sign-ups. To sign agents in with a subscription, run `HOME=/paperclip gosu node claude` in the same terminal.
+
+## 6. 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 and backups
+
+- **Update:** **Redeploy** pulls the newest image (restarts Paperclip, so do it when agents are idle).
+- **Backups:** Coolify can back up its own databases to S3-compatible storage; for Paperclip's volume, use your provider's server snapshots or the `tar` backup from the [VPS guide](/docs/host-vps#backups).
+- Keep Coolify itself updated from its settings page.
+
+## Troubleshooting
+
+- **No certificate:** the A record isn't pointing at the server yet, or Cloudflare's proxy is on.
+- **"This hostname is not allowed":** `PAPERCLIP_PUBLIC_URL` doesn't match the domain.
+- **Data reset after redeploy:** the volume isn't mounted at exactly `/paperclip`.
+- More: [Troubleshooting](/docs/troubleshooting).