Run Pi Pocket on a remote server

Create a VM#

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

ssh exe.dev new --name=my-pi-pocket
ssh my-pi-pocket.exe.xyz

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

Install Node.js 24#

Pi Pocket needs Node.js 22.19 or newer. NodeSource's package installs Node.js 24:

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

Expect v24.22.1 or later.

Install Pi Pocket#

Install it into ~/.local, a folder exedev owns, so Pi Pocket can update itself from its menu later:

npm install -g --prefix ~/.local --no-audit --no-fund pi-pocket@0.27
~/.local/bin/pi-pocket --help | head -1

The help starts Pi Pocket: a durable, multiplayer, mobile-first web app for Pi agents. npm warns that @google/genai and protobufjs have install scripts it didn't run; Pi Pocket needs neither.

Connect the models#

Pi Pocket uses Pi's own model settings in ~/.pi/agent. This file sends Pi's Anthropic and OpenAI models to exe.dev's LLM integration, which adds the credentials on its way out; the key in it is a placeholder. The Pi command line on this VM reads the same file:

mkdir -p ~/.pi/agent ~/projects
[ -s ~/.pi/agent/models.json ] || cat > ~/.pi/agent/models.json <<'EOF'
{
  "providers": {
    "anthropic": { "baseUrl": "https://llm.int.exe.xyz/anthropic", "apiKey": "exe-llm-integration" },
    "openai": { "baseUrl": "https://llm.int.exe.xyz/openai/v1", "apiKey": "exe-llm-integration" }
  }
}
EOF
cd ~/projects && pi -p --model anthropic/claude-haiku-5-5 "Reply with exactly: OK" </dev/null

Expect OK. If models.json already existed, the command left it alone: add the two providers to it yourself.

Start it#

systemd starts Pi Pocket at boot and restarts it if it stops. It listens on port 8000, so it's at https://<vm>.exe.xyz/; --access lan makes it listen on the VM's network address, where exe.dev's HTTPS proxy reaches it:

sudo tee /etc/systemd/system/pi-pocket.service >/dev/null <<'EOF'
[Unit]
Description=Pi Pocket
Wants=network-online.target
After=network-online.target

[Service]
User=exedev
WorkingDirectory=/home/exedev/projects
Environment=PATH=/home/exedev/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
ExecStart=/home/exedev/.local/bin/pi-pocket --access lan --port 8000 --cwd /home/exedev/projects
Restart=always
RestartSec=3
KillMode=mixed
TimeoutStopSec=20

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now pi-pocket
until curl -fso /dev/null localhost:8000/style.css; do sleep 1; done
systemctl is-enabled pi-pocket

Expect enabled. Check that Pi Pocket sees the models, using the owner token:

curl -fsS -H "Authorization: Bearer $(jq -r .ownerToken ~/.pi-pocket/config.json)" \
  localhost:8000/api/providers | jq -r '.[] | select(.configured) | .id'

Expect anthropic and openai.

Set up backups#

The backup script stops Pi Pocket for a few seconds, so the database is copied whole, and packs ~/.pi-pocket and ~/.pi/agent. It leaves out Pi's own program files and exe.dev's Pi extension, which come with the VM:

mkdir -p ~/pi-pocket-backups
sudo tee /usr/local/bin/pi-pocket-backup >/dev/null <<'EOF'
#!/bin/sh
# Back up Pi Pocket (~/.pi-pocket) and Pi's settings (~/.pi/agent) to
# ~/pi-pocket-backups/pi-pocket-<UTC time>.tar.gz. Keeps the newest 14.
# Pi Pocket stops while the database is copied; its runs resume after.
set -eu
cd /home/exedev
dest=pi-pocket-backups/pi-pocket-$(date -u +%Y%m%d-%H%M%S).tar.gz
systemctl stop pi-pocket
trap 'systemctl start pi-pocket' EXIT
tar -czf "$dest.partial" --exclude=.pi/agent/bin --exclude=.pi/agent/extensions/exe-dev .pi-pocket .pi/agent
systemctl start pi-pocket
trap - EXIT
chmod 600 "$dest.partial"
chown exedev: "$dest.partial"
mv "$dest.partial" "$dest"
ls -1 pi-pocket-backups/pi-pocket-*.tar.gz | head -n -14 | xargs -r rm --
echo "/home/exedev/$dest"
EOF
sudo chmod 755 /usr/local/bin/pi-pocket-backup

Take one and look inside:

backup=$(sudo pi-pocket-backup)
tar -tzf "$backup" | grep -E 'pocket.sqlite$|config.json$|models.json$'

Expect .pi-pocket/pocket.sqlite, .pi-pocket/config.json, and .pi/agent/models.json. Then back up every night:

sudo tee /etc/systemd/system/pi-pocket-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up Pi Pocket

[Service]
Type=oneshot
ExecStart=/usr/local/bin/pi-pocket-backup
EOF
sudo tee /etc/systemd/system/pi-pocket-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up Pi Pocket every night

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

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now pi-pocket-backup.timer
systemctl list-timers pi-pocket-backup.timer

The timer should list its next run. Installation done: sign in.

On the VM, sudo pi-pocket-backup takes an extra backup and prints its path. Take one before every update.

Go back to a backup#

This replaces sessions, people, settings and Pi's sign-ins with the backup's, and loses everything since. On the VM:

ls ~/pi-pocket-backups
sudo systemctl stop pi-pocket
rm -rf ~/.pi-pocket
tar -xzf ~/pi-pocket-backups/pi-pocket-20261031-033012.tar.gz -C ~
sudo systemctl start pi-pocket

Use a file from the listing in place of the example. The owner link is the backup's, so signed-in browsers stay signed in.

Move to a new VM#

On the new VM, follow Install by hand through Install Pi Pocket. Copy a backup across from your computer, for example scp ./pi-pocket-backups/pi-pocket-20261031-033012.tar.gz my-new-vm.exe.xyz:, then unpack it on the new VM with mkdir -p ~/projects && tar -xzf ~/pi-pocket-20261031-033012.tar.gz -C ~, and follow Start it and Set up backups. Copy your projects across too. Stop the old one first, on the old VM: sudo systemctl disable --now pi-pocket pi-pocket-backup.timer. The sign-in link now starts with the new VM's address, and everyone signs in there again.

Read the release notes first: some versions change the database for good, and then only the backup takes you back. Menu → Update Pi Pocket installs a new release and restarts it, going back by itself if it doesn't start. Or by hand, on the VM:

sudo pi-pocket-backup
npm install -g --prefix ~/.local --no-audit --no-fund pi-pocket@latest
sudo systemctl restart pi-pocket
journalctl -u pi-pocket -n 30 --no-pager | grep -F 'Pi Pocket'

The log should end with Pi Pocket ● running. Betas (pi-pocket@beta) come out almost daily; they're tested less, and can change stored data.

On the VM:

systemctl status pi-pocket --no-pager
journalctl -u pi-pocket -n 50 --no-pager

• The model picker says No models are available: check ~/.pi/agent/models.json (jq . ~/.pi/agent/models.json shows a typo), then restart Pi Pocket. curl https://llm.int.exe.xyz/v1/models lists what the LLM integration offers this VM.
• A model fails with a sign-in error: that provider has a line in models.json and your own sign-in. Keep one of the two (see the FAQ).
• The sign-in page keeps coming back: Pi Pocket's cookie belongs to one address. Use https://my-pi-pocket.exe.xyz/, not the http://10… address the log prints.
• Signed out everywhere, or a link leaked: stop the service, run ~/.local/bin/pi-pocket --rotate-token --access lan --port 8000 once and press q when it's up, then start the service. Every device that used the old link must sign in again.
• EADDRINUSE in the log: something else listens on port 8000.