← All articles

Why Render for Paperclip

Render handles infrastructure so you don't have to. Free SSL, automatic deploys from GitHub, health checks, and a persistent disk system make it a solid choice for running Paperclip without touching a server. The main caveat: free-tier services spin down after 15 minutes of inactivity — for Paperclip, you need a paid plan ($7/month) to keep agents always-on.

Prerequisites

• A Render account (render.com)
• Your Paperclip source code in a GitHub or GitLab repo
• Basic familiarity with environment variables

Step 1: Prepare your Paperclip repo

Render deploys from a git repo. If you're running Paperclip as a Node app, make sure your repo has a package.json with a start script:

{
  "scripts": {
    "start": "paperclipai server start --port $PORT --host 0.0.0.0"
  }
}

Or use Docker (see Step 3 alternative).

Step 2: Create a Web Service

1. In the Render dashboard, click New → Web Service
2. Connect your GitHub repo
3. Configure the service:
   • Name: paperclip
   • Region: Choose closest to your users
   • Branch: main
   • Runtime: Node
   • Build Command: npm install
   • Start Command: npm start
   • Instance Type: Starter ($7/month) — required for always-on

Step 3: Docker alternative (recommended)

If you prefer Docker, create a Dockerfile in your repo root:

FROM node:20-alpine
WORKDIR /app
RUN npm install -g paperclipai
RUN mkdir -p /data
EXPOSE 10000
CMD ["npx", "paperclipai", "server", "start", "--port", "10000", "--host", "0.0.0.0"]

Note: Render uses port 10000 by default. Set PORT=10000 or configure explicitly.

Step 4: Add a persistent disk

Paperclip stores its database and workspace data on disk. Without persistence, all data resets on every deploy.

1. In your Web Service settings, go to Disks
2. Click Add Disk
3. Configure:
   • Name: paperclip-data
   • Mount Path: /data
   • Size: 1 GB (upgradeable)
4. Save changes

Step 5: Set environment variables

In your Web Service settings under Environment:

NODE_ENV=production
PAPERCLIP_DATA_DIR=/data
BETTER_AUTH_SECRET=<generate with: openssl rand -hex 32>
PORT=10000

Generate BETTER_AUTH_SECRET locally and paste it in. Never commit secrets to your repo.

Step 6: Deploy

Click Deploy (or push to your connected branch). Render pulls your code, runs the build command, and starts the service.

Watch the deploy logs in real time from the Render dashboard.

Step 7: First-time setup

Once the service is live, open the URL Render assigned (e.g. https://paperclip.onrender.com). Complete the admin setup wizard to create your account and configure your Paperclip company.

Step 8: Custom domain

1. Go to Settings → Custom Domains in your service
2. Add your domain (e.g. paperclip.yourdomain.com)
3. In your DNS, create a CNAME record pointing to your .onrender.com URL

Render provisions a free Let's Encrypt certificate within a few minutes.

Auto-deploy on push

Render redeploys automatically every time you push to your configured branch. To disable, go to Settings → Auto-Deploy and toggle it off — useful when you want to control when updates go live.

Common errors

Service spinning down: Free-tier Render services sleep after 15 minutes of inactivity. Upgrade to Starter ($7/month) and set health checks to keep Paperclip alive for agent heartbeats.

Port mismatch: If your app starts on port 3100 but Render expects 10000, set the PORT environment variable and make sure your start command reads from $PORT.

Data lost after redeploy: This happens when the persistent disk isn't mounted. Verify the disk mount path matches PAPERCLIP_DATA_DIR in your env.

Health checks

Add a health check in your Render service settings:

• Path: /api/health
• Interval: 30 seconds

This tells Render to restart your service if Paperclip stops responding.

Cost

• Starter plan: $7/month (required for always-on, no sleep)
• Persistent disk: $0.25/GB/month
• Total for basic Paperclip: ~$7.25/month

Railway gives you $20 free credit and a simpler deploy path — no Dockerfile required.

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.