← All articles

Why Fly.io for Paperclip

Fly.io runs your app in Firecracker micro-VMs distributed across 30+ regions. For Paperclip, that means low-latency access from anywhere, automatic restarts on crash, and a persistent volume system that survives redeploys. The free tier gives you 3 shared-CPU VMs and 3 GB of persistent storage — enough for a personal Paperclip instance at zero cost.

Prerequisites

• A Fly.io account (free at fly.io)
• flyctl installed on your local machine
• Docker installed locally (optional but recommended for testing)

Step 1: Install flyctl

# macOS
brew install flyctl

# Linux
curl -L https://fly.io/install.sh | sh

# Windows (PowerShell)
pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"

Authenticate:

fly auth login

Step 2: Create the Fly app

In your project directory (or a new folder for Paperclip):

mkdir paperclip-fly && cd paperclip-fly
fly launch --name paperclip-myinstance --region iad --no-deploy

Choose "No" when asked to deploy immediately. You'll configure the fly.toml first.

Step 3: Write the Dockerfile

Fly.io builds from a Dockerfile. Create one in your project root:

FROM node:20-alpine

WORKDIR /app

RUN npm install -g paperclipai

RUN mkdir -p /data

EXPOSE 3100

CMD ["npx", "paperclipai", "server", "start", "--port", "3100", "--host", "0.0.0.0"]

Step 4: Configure fly.toml

Open the generated fly.toml and update it:

app = "paperclip-myinstance"
primary_region = "iad"

[build]
  dockerfile = "Dockerfile"

[env]
  PORT = "3100"
  NODE_ENV = "production"

[http_service]
  internal_port = 3100
  force_https = true
  auto_stop_machines = false
  auto_start_machines = true
  min_machines_running = 1

[[mounts]]
  source = "paperclip_data"
  destination = "/data"
  initial_size = "3gb"

[[vm]]
  memory = "1gb"
  cpu_kind = "shared"
  cpus = 1

Set auto_stop_machines = false and min_machines_running = 1 — Paperclip agents need the instance always running to fire heartbeats.

Step 5: Create the persistent volume

fly volumes create paperclip_data --size 3 --region iad

This creates 3 GB of persistent storage. Paperclip stores its SQLite database and all agent workspace data here. Without a volume, your data resets on every deploy.

Step 6: Set secrets

fly secrets set PAPERCLIP_DATA_DIR=/data
fly secrets set BETTER_AUTH_SECRET=$(openssl rand -hex 32)
fly secrets set NODE_ENV=production

BETTER_AUTH_SECRET signs all authentication tokens — use a strong random value.

Step 7: Deploy

fly deploy

Watch the build and startup:

fly logs

Step 8: First-time setup

fly open

Opens https://paperclip-myinstance.fly.dev. Complete the setup wizard to create your admin account.

Step 9: Custom domain (optional)

fly certs add paperclip.yourdomain.com

Add a CNAME in your DNS pointing to paperclip-myinstance.fly.dev. Fly.io handles Let's Encrypt certificates automatically.

Updating Paperclip

Update the version in your Dockerfile and redeploy:

fly deploy

Zero-downtime rolling deploys are the default.

Common errors

Volume not mounted: If Paperclip can't write to /data, check that fly.toml has the [[mounts]] block and the volume was created in the same region as your VM.

Machine auto-stopping: If your instance goes to sleep, set auto_stop_machines = false in fly.toml and redeploy.

Out of memory: Upgrade from 256 MB to 1 GB in fly.toml under [[vm]]. Paperclip needs at least 512 MB for stable operation.

Cost

A 1 GB RAM shared-CPU VM costs about $5.70/month. Add $0.15/GB/month for storage. Total: ~$6–7/month for a full Paperclip instance.

Want the easiest path? Railway gives you $20 free credit and deploys with zero Dockerfile setup.

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.