Skip to main content

Running Paperclip on a Hetzner VPS: A Proper Setup Guide

This post covers how I set up Paperclip, an open-source AI agent orchestration platform, on a dedicated Hetzner VPS. It picks up where my previous Hetzner guide left off, so if you haven't read that one, start there. By the end, you'll have Paperclip running persistently behind Caddy with HTTPS, locked down with basic auth, and accessible from anywhere via a subdomain.

Why a Dedicated VPS

You can run Paperclip locally, and for experimenting that's fine. But agents running autonomously on a schedule — waking up every 30 seconds, checking their inbox, executing tasks — don't belong on your laptop. A few reasons to give Paperclip its own server:

Isolation. Agents can spike CPU and memory unpredictably. You don't want that affecting other services you're running.

Persistence. Paperclip tracks agent sessions, conversation history, and task state. None of that survives a reboot or a closed terminal without a proper process manager.

Always-on. The whole point of autonomous agents is that they work while you're not watching. That requires a server.

I put it on a separate VPS rather than sharing with my existing setup. A Hetzner CX22 (2 vCPU, 4 GB RAM, Singapore region for latency) costs around €6/month.

Provisioning the Server

The full provisioning and hardening steps — SSH lockdown, fail2ban, Tailscale, UFW — are covered in my Hetzner VPS setup guide. Follow that first and come back here once you have a hardened server with a deploy user and Tailscale running.

A few things specific to this setup worth noting:

Use a dedicated VPS, not a shared one. Paperclip agents can be resource-hungry. Keep it isolated from other services.

Region: Pick whatever's geographically closest to you. I chose Singapore for lower latency from Bangkok.

Size: Go with Regular Performance CX22 (2 vCPU, 4 GB RAM). Claude Code is memory-hungry — the 2 GB CX11 would be tight. Skip Cost-Optimized (older hardware) and Dedicated Resources (overkill for this use case).

Create a deploy user before proceeding. Don't run Paperclip as root. The previous guide covers this — make sure you have a deploy user with sudo access and your SSH key copied across before continuing.

Installing Node.js and Claude Code

Switch to the deploy user and create a workspace:

su - deploy
mkdir ~/paperclip
cd ~/paperclip

Paperclip runs on Node.js. Install it from the NodeSource repository:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Install Claude Code globally:

sudo npm install -g @anthropic-ai/claude-code

Authenticate Claude Code. This opens a browser OAuth flow. Complete it on your local machine:

claude

Follow the prompts to trust the directory and complete login.

Configure MCP Servers (Optional)

If you want your agents to have access to tools like Linear, or other services, add them now as the deploy user. The --scope user flag makes the config available to all Claude Code sessions running as this user, including Paperclip's agents:

claude mcp add linear --transport sse https://mcp.linear.app/sse \
  --header "Authorization: Bearer YOUR_LINEAR_API_KEY" \
  --scope user

Installing Paperclip

Run the interactive setup:

npx paperclipai onboard --yes

This creates an embedded PostgreSQL database, generates secrets, and writes a config to ~/.paperclip/. When it's done, you'll see a summary confirming everything passed.

Start the server once to verify it works:

npm paperclipai run

You should see the Paperclip ASCII banner and Server listening on 127.0.0.1:3100. Kill it with Ctrl+C once confirmed.

Paperclip starting up — the ASCII banner confirms the server is running

Setting Up Caddy

Install Caddy:

sudo apt install -y caddy

Add a DNS A record for your subdomain pointing to the server's public IP. I used paperclip.rendal.me. Set it to DNS-only (not proxied) in Cloudflare.

Generate a hashed password for basic auth:

caddy hash-password

Enter your password when prompted and copy the hash it outputs. Edit the Caddyfile:

sudo nano /etc/caddy/Caddyfile

Replace the entire contents with:

paperclip.your-domain.com {
    basicauth {
        yourname HASHED_PASSWORD_HERE
    }
    reverse_proxy 127.0.0.1:3100
}

Restart Caddy:

sudo systemctl restart caddy

Caddy will automatically provision a TLS certificate.

Running Paperclip as a Service

Right now Paperclip dies when you close the SSH session. Fix that with systemd:

sudo nano /etc/systemd/system/paperclip.service
[Unit]
Description=Paperclip AI Orchestration
After=network.target

[Service]
User=deploy
WorkingDirectory=/home/deploy/paperclip
ExecStart=/usr/bin/npx paperclipai run
Restart=always
RestartSec=10
Environment=HOME=/home/deploy

[Install]
WantedBy=multi-user.target

Enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable paperclip
sudo systemctl start paperclip

Check it's running:

sudo systemctl status paperclip

Paperclip now starts automatically on boot and restarts if it crashes.

Visit https://paperclip.your-domain.com – You should see a login prompt, and after authenticating, the Paperclip onboarding screen.

The Paperclip dashboard after a successful setup

What You Now Have

After all of this:

  • Paperclip is running persistently as a systemd service under the deploy user
  • HTTPS is handled by Caddy with automatic certificate renewal
  • Basic auth protects the UI from the public internet
  • SSH is invisible to the internet — accessible only through Tailscale
  • Claude Code is authenticated and optionally connected to MCP servers
  • Agents can run autonomously 24/7 without your laptop being open

The next step is configuring your LLM provider in the Paperclip UI, creating your first company, and giving your agents something real to do. That's a separate post.