Self-host Paperclip

On your computer (pick another name if my-paperclip is taken):

ssh exe.dev new --name=my-paperclip
ssh my-paperclip.exe.xyz

All remaining installation commands run on the VM, as exedev.

Install Node.js 24#

Paperclip needs Node.js 24.11 or later:

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

Expect v24. and something.

Install Paperclip#

Paperclip publishes builds daily. Pin a tested stable release; the installer keeps it in ~/.paperclip/cli and puts paperclipai in ~/.local/bin:

npx -y paperclipai@2026.1023.0 install --version 2026.1023.0 --yes
export PATH="$HOME/.local/bin:$PATH"
paperclipai --version

Expect 2026.1023.0 (managed npm pinned; …). It takes about a minute; warnings about EBADENGINE are harmless.

Set up the server#

--bind lan puts Paperclip in authenticated mode, so everyone signs in. It listens on port 8000, where the HTTPS proxy sends the VM's address, and accepts only that hostname. Lingering keeps the service running after you log out:

sudo loginctl enable-linger "$USER"
PORT=8000 PAPERCLIP_ALLOWED_HOSTNAMES="$(hostname).exe.xyz" \
  paperclipai onboard --yes --bind lan --install-service

That writes ~/.paperclip/instances/default, with generated secrets in .env and secrets/master.key, then starts the service. Check it:

sleep 5
loginctl show-user "$USER" -p Linger
systemctl --user is-enabled paperclipai
systemctl --user is-active paperclipai
curl -fsS --retry 10 --retry-connrefused --retry-delay 3 \
  -H "Host: $(hostname).exe.xyz" http://127.0.0.1:8000/api/health |
  jq -r '.status, .deploymentMode, .deploymentExposure'

Expect Linger=yes, enabled, active, then ok, authenticated, and private.

Set up nightly backups#

The archive is taken with Paperclip stopped, so the database in it is consistent. A run in progress is stopped and retried after the restart:

mkdir -p ~/.config/systemd/user ~/backups/paperclip
chmod 700 ~/backups ~/backups/paperclip
cat > ~/.config/systemd/user/paperclip-backup.service <<'EOF'
[Unit]
Description=Paperclip backup

[Service]
Type=oneshot
UMask=0077
ExecStartPre=/usr/bin/systemctl --user stop paperclipai.service
ExecStart=/bin/sh -c 'tar -C %h/.paperclip/instances -czf %h/backups/paperclip/paperclip-$$(date +%%Y%%m%%d-%%H%%M).tar.gz default && find %h/backups/paperclip -name "paperclip-*.tar.gz" -mtime +13 -delete'
ExecStopPost=/usr/bin/systemctl --user start paperclipai.service
EOF
cat > ~/.config/systemd/user/paperclip-backup.timer <<'EOF'
[Unit]
Description=Nightly Paperclip backup

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now paperclip-backup.timer
systemctl --user start paperclip-backup.service
tar -tzf "$(ls -t ~/backups/paperclip/paperclip-*.tar.gz | head -1)" | grep -c 'default/config.json'
systemctl --user is-active paperclipai
systemctl --user list-timers paperclip-backup.timer

Expect 1, active, and a scheduled next run.

Make yourself the admin#

Create the one-time link that makes its user the instance admin:

paperclipai auth bootstrap-ceo --base-url "https://$(hostname).exe.xyz"

Open the Invite URL it prints and carry on from Make yourself the admin.

On the VM, take a fresh archive now (Paperclip stops for a few seconds):

systemctl --user start paperclip-backup.service
ls -t ~/backups/paperclip | head -3

To restore, replace BACKUP.tar.gz with the archive's filename. The old folder is kept beside it until you delete it:

systemctl --user stop paperclipai &&
mv ~/.paperclip/instances/default ~/.paperclip/instances/default.old &&
tar -C ~/.paperclip/instances -xzf ~/backups/paperclip/BACKUP.tar.gz &&
systemctl --user start paperclipai

Sign in again and check your tasks are there. Moving to a new VM? Install there first, copy the archive over with scp, restore, then let the new hostname in and restart:

paperclipai allowed-hostname "$(hostname).exe.xyz"
systemctl --user restart paperclipai

Paperclip's own hourly database dumps are in ~/.paperclip/instances/default/data/backups, kept for 30 days.

Paperclip ships a stable release every week or two, and nightly and canary builds in between; stay on stable. Find the newest version on the releases page and read its notes. Then, on the VM, take an archive, stop Paperclip, and update, replacing VERSION:

systemctl --user start paperclip-backup.service &&
systemctl --user stop paperclipai &&
paperclipai update --version VERSION --no-backup &&
systemctl --user start paperclipai &&
paperclipai --version &&
systemctl --user is-active paperclipai

Expect the new version and active; the new version updates the database as it starts. Sign in and check your tasks.

Note

Don't run paperclipai update with the service running. In authenticated mode it can't read the new version from the server, so it waits a minute, then switches back to the old version, which is left with a database the new one may have changed. The archive replaces the database's own pre-update dump, which needs the service running.

If the new version misbehaves, stop the service and run paperclipai update --rollback, then restore the archive you just took: rollback switches the program back but not the database.

Ask Shelley, or check on the VM:

systemctl --user is-active paperclipai
journalctl --user -u paperclipai -n 40 --no-pager
curl -fsS -H "Host: $(hostname).exe.xyz" http://127.0.0.1:8000/api/health | jq -r .status

• paperclipai: command not found? Run source ~/.profile, or log in again.
• 502 from the dashboard? Paperclip takes a few seconds to start; reload. Still there? Look for errors in the log above.
• 403 or "hostname not allowed"? The VM's address isn't in Paperclip's list. Run paperclipai allowed-hostname "$(hostname).exe.xyz" and systemctl --user restart paperclipai.
• "Project authentication settings conflict with the selected AI connection"? Something wrote API settings to ~/.claude/settings.json or ~/.codex/config.toml (exeuntu configure does). Move the file aside and run the test again.
• "The provider rejected this API key"? You used API key rather than Advanced: that option checks keys with Anthropic or OpenAI directly. Use the custom gateway above.
• An agent run fails? Open the run on the task page for its log, and check your LLM integration.