← All articles

Is a Raspberry Pi good enough for Paperclip?

Raspberry Pi 4 (4 GB): Yes, works well for personal use with 1–3 agents.

Raspberry Pi 4 (2 GB): Works for light use. Can be tight with concurrent agent runs.

Raspberry Pi 4 (1 GB) or earlier models: Not recommended — too little RAM.

Raspberry Pi 5 (4 GB or 8 GB): Excellent. Significantly faster than Pi 4, more headroom.

The Pi 4's ARM Cortex-A72 CPU is adequate for Paperclip's Node.js workloads. It's not fast, but Paperclip is mostly I/O-bound (waiting on API responses), not CPU-bound.

Hardware needed

• Raspberry Pi 4 (4 GB or 8 GB) or Pi 5
• MicroSD card (32 GB minimum, Class 10 / U3 speed rating)
• Power supply (official Pi 4 USB-C supply, 3A)
• Ethernet cable (recommended over WiFi for reliability)
• Optionally: case with active cooling

Step 1: Flash the OS

1. Download Raspberry Pi Imager from raspberrypi.com
2. Flash Raspberry Pi OS Lite (64-bit) to your SD card
   • In the Imager settings, enable SSH, set username/password, configure WiFi if needed
3. Insert the SD card and power on

Find the Pi's IP on your router's admin page or with nmap -sn 192.168.1.0/24.

Step 2: Connect and update

ssh pi@RASPBERRY_PI_IP
# (or whatever username you set)

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git nginx ufw

Step 3: Install Node.js 20

The Raspberry Pi uses ARM64 (aarch64). NodeSource supports it natively:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node --version  # v20.x.x

Step 4: Install Paperclip

sudo npm install -g paperclipai

mkdir -p ~/paperclip/data

Create ~/paperclip/.env:

cat > ~/paperclip/.env << 'EOF'
NODE_ENV=production
PAPERCLIP_DATA_DIR=/home/pi/paperclip/data
BETTER_AUTH_SECRET=REPLACE_WITH_RANDOM_SECRET
PAPERCLIP_LISTEN_PORT=3100
PAPERCLIP_LISTEN_HOST=127.0.0.1
PAPERCLIP_MIGRATION_AUTO_APPLY=true
PAPERCLIP_MIGRATION_PROMPT=never
EOF
chmod 600 ~/paperclip/.env

Step 5: Systemd service

sudo tee /etc/systemd/system/paperclip.service << EOF
[Unit]
Description=Paperclip AI
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/paperclip
EnvironmentFile=/home/pi/paperclip/.env
ExecStart=/usr/bin/npx paperclipai server start
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now paperclip

Note After=network-online.target — the Pi should wait for internet before starting Paperclip (especially important for home networks where DHCP takes a moment).

Step 6: nginx

sudo tee /etc/nginx/sites-available/paperclip << 'EOF'
server {
    listen 80;
    server_name paperclip.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3100;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/paperclip /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Step 7: Dynamic DNS (for home internet)

Home internet usually has a dynamic IP — it changes periodically. Use a dynamic DNS service so your domain always points to your home IP.

Free options: Duck DNS, No-IP, Afraid.org

Duck DNS setup:

1. Sign up at duckdns.org
2. Create a subdomain (e.g., mypaper.duckdns.org)
3. Install the update client:

mkdir ~/duckdns
cat > ~/duckdns/duck.sh << 'EOF'
echo url="https://www.duckdns.org/update?domains=YOUR_DOMAIN&token=YOUR_TOKEN&ip=" | curl -k -o ~/duckdns/duck.log -K -
EOF
chmod +x ~/duckdns/duck.sh

# Run every 5 minutes via cron
crontab -e
# Add: */5 * * * * ~/duckdns/duck.sh >/dev/null 2>&1

Step 8: Port forwarding

In your home router's admin panel, forward ports 80 and 443 to your Pi's local IP.

Example (varies by router):

• External port 80 → Internal IP 192.168.1.X, port 80
• External port 443 → Internal IP 192.168.1.X, port 443

Step 9: SSL

Once your domain resolves to your home IP and port forwarding is configured:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.duckdns.org

Reliability considerations

A Pi at home isn't as reliable as a cloud VPS:

• Power outages: A UPS (uninterruptible power supply) keeps the Pi running during brief outages
• Internet outages: Not much you can do — agents won't run when the network is down
• SD card wear: Write-heavy workloads degrade SD cards over time. Use a fast A2-rated card and consider booting from USB SSD

For mission-critical Paperclip use, a cloud VPS is more reliable. For personal use where occasional downtime is acceptable, the Pi is excellent.

Cost

• Raspberry Pi 4 (4 GB): ~$75 one-time
• MicroSD card: ~$10
• Electricity: ~$4/year (3W × 24/7)
• After hardware payback (vs. $5/month VPS): free in ~18 months

Railway gives you $20 free credit to get started if you prefer cloud infrastructure over home hardware.

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.