← All articles

Before updating

1. Check the changelog — visit the Paperclip releases page to see what's new and any breaking changes
2. Backup your data — especially before major version updates:

# VPS: backup data directory
sudo systemctl stop paperclip
tar -czf ~/paperclip-backup-$(date +%Y%m%d).tar.gz /opt/paperclip/data
sudo systemctl start paperclip

3. Note your current version: npx paperclipai --version

Updating on a VPS (npm global install)

# Update Paperclip
sudo npm install -g paperclipai@latest

# Verify new version
paperclipai --version

# Restart the service
sudo systemctl restart paperclip

# Check it started correctly
sudo systemctl status paperclip
journalctl -u paperclip -n 20

Database migrations run automatically on startup when PAPERCLIP_MIGRATION_AUTO_APPLY=true. If you haven't set this, Paperclip will prompt you interactively — set it to avoid the prompt:

echo "PAPERCLIP_MIGRATION_AUTO_APPLY=true" >> /opt/paperclip/.env
echo "PAPERCLIP_MIGRATION_PROMPT=never" >> /opt/paperclip/.env

Updating with Docker Compose

# In docker-compose.yml, pin the version or use latest
services:
  paperclip:
    image: node:20-alpine
    command: sh -c "npm install -g paperclipai@latest && npx paperclipai server start ..."

To update:

# Pull fresh base image and reinstall
docker compose down
docker compose up -d --force-recreate

# Or just restart (re-runs npm install which picks up latest)
docker compose restart paperclip

To pin a specific version (recommended for production):

command: sh -c "npm install -g paperclipai@1.5.0 && npx paperclipai server start ..."

Then update the version number in docker-compose.yml when you're ready to upgrade.

Updating on Railway

Railway redeploys automatically on git push if you're deploying from a repo. To update:

1. Update the Paperclip version in your Dockerfile or package.json
2. Push to your connected branch — Railway redeploys automatically

Or trigger a manual redeploy from the Railway dashboard:

1. Go to your service
2. Click the three dots (⋮) menu
3. Select Redeploy

Railway automatically applies database migrations and handles zero-downtime deployments.

Updating on Fly.io

# Update the Paperclip version in your Dockerfile
# Then redeploy
fly deploy

# Watch the deployment
fly logs

Fly.io does rolling deploys by default — your instance stays up while the new version is being deployed.

Updating on Render

Render auto-deploys on git push. To update:

1. Update the Paperclip version in your repo (Dockerfile or package.json)
2. Push to your connected branch
3. Render automatically redeploys

Or trigger a manual deploy from the Render dashboard → your service → Manual Deploy → Deploy latest commit.

Updating to a major version

Major version updates (e.g., 1.x → 2.x) may include breaking changes or database migrations that can't be automatically reversed.

Steps for major updates:

1. Read the migration guide in the release notes
2. Back up your data (see above)
3. Test on a staging instance if you have one
4. Update during low-activity hours to minimize disruption
5. Follow the same update steps for your platform

Checking if a migration ran

After updating, verify the database migration completed:

journalctl -u paperclip --since "5 minutes ago" | grep -i "migration"

You should see something like:

Migration applied: 20250115_add_agent_budgets
Migration applied: 20250120_execution_policies

Rolling back an update

If an update causes issues:

VPS:

# Downgrade to specific version
sudo npm install -g paperclipai@1.4.2
sudo systemctl restart paperclip

Docker Compose:

Change the version in your docker-compose.yml and restart:

docker compose up -d --force-recreate

Database rollback: Paperclip migrations are not always reversible. If you've run migrations and need to roll back, restore from your pre-update backup.

Update notifications

Subscribe to Paperclip's GitHub releases to be notified of new versions:

1. Go to the Paperclip GitHub repo
2. Click Watch → Custom → Releases
3. You'll get an email for each new release

Common update errors

Migration failed — database locked: Another Paperclip process is running. Stop it, then update.

npm permission error: Run with sudo: sudo npm install -g paperclipai@latest

paperclipai: command not found after update: npm global bin directory isn't in PATH. Check: npm root -g and add the parent bin directory to your PATH.

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.