papercliped 2.2.1 → 2.4.0

package/site/docs/faq.md

@@ -12,12 +12,27 @@ 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).
 
+## Why was a call blocked, or a tool missing?
+Your own settings. Open **Papercliped** in Paperclip: the switch (API only, Full, Agent only), an agent's setting, or the session's tool and agent lists decide what an AI app may do, and **Activity** shows each blocked call and the reason. See [API only, Full or Agent only](/docs/access-modes).
+
+## Can I keep an agent away from AI apps?
+Yes. In the [control room](/docs/control-room), open **Agents** and set it to **Off**: AI apps can't see it, touch it, or see what's assigned to it.
+
 ## How do I stop it?
 Disconnect the app on the manage page, revoke the key in your Paperclip, or delete your account. It stops at once.
 

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
@@ -30,7 +30,7 @@ This starts a local server for one Paperclip, using `PAPERCLIP_API_URL` and `PAP
 Any app that supports MCP can use Papercliped. See [Any AI app (MCP)](/docs/other-ai-apps).
 
 ## Inside your Paperclip
-The Papercliped plugin for Paperclip is where you manage everything: connected apps, levels, privacy and your account. See [Paperclip plugin](/docs/paperclip-plugin).
+The Papercliped plugin for Paperclip is where you manage everything: the [control room](/docs/control-room) for connected apps, what each may do and which agents it applies to, plus privacy and your account. See [Paperclip plugin](/docs/paperclip-plugin).
 
 ## ChatGPT
 Papercliped publishes an OpenAPI description at `{{MCP}}/openapi.json` for GPT Actions. See [ChatGPT setup](/docs/chatgpt).

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).

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).