Skip to content

Self-host PocketBase

A whole backend in one file, on a disk that stays put.

Deploy on exe.dev

Shelley handles the setup. About 10 minutes.

Prefer a terminal?
curl -fsSL https://exe.dev/deploy/pocketbase/prompt.txt | ssh exe.dev new --prompt=/dev/stdin

PocketBase is a backend in a single file: a database, user accounts, file storage, an admin dashboard, a REST API, and realtime subscriptions. It wants exactly what an exe.dev VM is: one machine with a disk that stays put.

exe.dev adds what PocketBase leaves to you. HTTPS and a login wall come from the HTTPS proxy, so the app is private until you share it, and every request says who is signed in with an X-ExeDev-Email header your API rules can use. The VM can send you email and call LLMs without a password or an API key on disk. Shelley, the agent on your VM, can write your hooks and migrations, and the recipe below keeps the superuser dashboard off the internet even after your app goes public.

What you get#

  • PocketBase running under systemd, back after a reboot.
  • A superuser for your exe.dev email, with a random password kept in a mode 600 file.
  • A private dashboard on port 8090 and an app port, 8000, that is safe to make public.
  • A live notes page that shows realtime updates through exe.dev's proxy.
  • Nightly backups, and an encryption key for PocketBase's settings, kept in a mode 600 file.
What's running, and where
Private https://my-pocketbase.exe.xyz:8090/_/ The dashboard and the full API, for you
Private https://my-pocketbase.exe.xyz/ Your app and its API; public once you share it, superusers refused
my-pocketbase.exe.xyz exe.dev VM
PocketBase 0.42.3 The prebuilt binary, run by systemd; SQLite inside :8090~/pocketbase/pb_data
Public-ready port nginx; your app and its API, never superusers :8000
JS hooks Email through exe.dev, superusers kept private ~/pocketbase/pb_hooks
Nightly backups PocketBase's own, at 03:00 UTC, seven kept ~/pocketbase/pb_data/backups

Deploy with Shelley#

Click Deploy and Shelley will set up PocketBase on a new VM, then check that it works. No config-file wrangling required.

Prefer a terminal?
curl -fsSL \
  https://exe.dev/deploy/pocketbase/prompt.txt \
  | ssh exe.dev new --prompt=/dev/stdin
What Shelley is told
Set up PocketBase on this VM by following the exe.dev recipe at https://exe.dev/deploy/pocketbase.md from top to bottom.

The recipe's example VM name is my-pocketbase. This VM's name is the output of `hostname`: use it wherever the recipe writes my-pocketbase. Skip the step that creates the VM; you are on it.

You are done when all of these are true. Check each one yourself:
- PocketBase running under systemd, back after a reboot.
- A superuser for your exe.dev email, with a random password kept in a mode 600 file.
- A private dashboard on port 8090 and an app port, 8000, that is safe to make public.
- A live notes page that shows realtime updates through exe.dev's proxy.
- Nightly backups, and an encryption key for PocketBase's settings, kept in a mode 600 file.

Read the whole recipe, including closed details, and follow "Install by
hand" first. The opening walkthrough is for the owner afterwards.
Work as exedev in ~/pocketbase. Do not make the VM public, set up SMTP
or S3, or run the later Restore, Update, or Go framework instructions.
Never print the superuser password or the encryption key into the chat.
Verify each step as the recipe says: the service is enabled and healthy,
port 8000 serves the notes page and refuses superuser sign-in with 403,
and port 8090 accepts the superuser's password.
Finish with the dashboard URL on port 8090 and the app URL, and tell the
owner the password is in ~/pocketbase/superuser.txt.

Finish with the URLs I should open.

Also at /deploy/pocketbase/prompt.txt. The recipe it follows is /deploy/pocketbase.md.

Sign in to the dashboard#

Open https://my-pocketbase.exe.xyz:8090/_/ and sign in to exe.dev. Then sign in to PocketBase. Shelley made a superuser for your exe.dev email with a random password; to see it, on your computer:

ssh my-pocketbase.exe.xyz cat pocketbase/superuser.txt

Keep the password in your password manager. Port 8090 only answers people signed in to exe.dev as you, so the dashboard has two locks: your exe.dev login and the PocketBase password.

Watch it live#

Open https://my-pocketbase.exe.xyz/. It's a small page served from ~/pocketbase/pb_public, built on a notes collection. Add a note. Open the page in a second tab and add another: it appears in both at once, through PocketBase's realtime API.

The live notes page: a text box, an Add button, and a list of notes with times
The notes page. New notes arrive over PocketBase's event stream, no reload.

In the dashboard, open Collections → notes and edit a note: the page changes as you save. Look at the collection's API rules, too. Anyone may list and view notes, but the create rule is @request.headers.x_exedev_email != '': only people signed in to exe.dev can add one.

Build your backend#

Make collections in the dashboard. PocketBase writes each change to ~/pocketbase/pb_migrations as a JavaScript migration, so your schema is in files you can keep in git and replay on another VM.

Your frontend can talk to PocketBase from anywhere with the JavaScript SDK:

import PocketBase from "pocketbase";

const pb = new PocketBase("https://my-pocketbase.exe.xyz");
const notes = await pb.collection("notes").getList(1, 20, { sort: "-created" });
pb.collection("notes").subscribe("*", (e) => console.log(e.action, e.record));

Or serve it from PocketBase itself: whatever you put in ~/pocketbase/pb_public is served at https://my-pocketbase.exe.xyz/.

Server code goes in ~/pocketbase/pb_hooks as *.pb.js files, and PocketBase restarts itself when one changes. Two are there already: exe-email.pb.js and private-superusers.pb.js. Here's a third: a route that asks an LLM to sum up the notes. The VM calls exe.dev's LLM integration with no API key, billed to your exe.dev account. On the VM:

cat > ~/pocketbase/pb_hooks/summary.pb.js <<'EOF'
/// <reference path="../pb_data/types.d.ts" />
routerAdd("GET", "/api/notes/summary", (e) => {
    // Only for people signed in to exe.dev: this spends your LLM credits.
    if (!e.requestInfo().headers["x_exedev_email"]) {
        throw new UnauthorizedError("Sign in to exe.dev first.")
    }
    const notes = e.app.findRecordsByFilter("notes", "", "-created", 50, 0)
    const res = $http.send({
        url: "https://llm.int.exe.xyz/v1/chat/completions",
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
            model: "gpt-6-luna",
            messages: [{
                role: "user",
                content: "Sum up these notes in two sentences:\n" +
                    notes.map((n) => n.getString("text")).join("\n"),
            }],
        }),
        timeout: 120,
    })
    if (res.statusCode !== 200) {
        throw new BadRequestError("LLM: HTTP " + res.statusCode)
    }
    return e.json(200, { summary: res.json.choices[0].message.content })
})
EOF

Open https://my-pocketbase.exe.xyz/api/notes/summary. On the VM, curl -s https://llm.int.exe.xyz/v1/models lists the models you can use.

Rather not write it yourself? Ask Shelley at https://my-pocketbase.shelley.exe.xyz/: "Add a tasks collection that only its owner can see, and a hook that emails me when one is overdue." Shelley can read your hooks, the dashboard's migrations, and the logs.

Let people in#

To start, only you can reach either port. To let a friend use your app, on your computer:

ssh exe.dev share add my-pocketbase friend@example.com

They sign in to exe.dev, and PocketBase sees their email in @request.headers.x_exedev_email, ready for API rules such as @request.headers.x_exedev_email = owner_email. No accounts or passwords to build. See sharing for teams and share links.

To go public, review each collection's API rules first (an empty rule means anyone), then on your computer:

ssh exe.dev share set-public my-pocketbase

Now anyone can reach https://my-pocketbase.exe.xyz/: your pb_public files and PocketBase's API, protected by your rules. Visitors who sign in to exe.dev at /__exe.dev/login?redirect=/ still bring their email header; nobody else can fake it. Superusers are refused on this port, with a password or without (the dashboard there just says "Superusers use the private port."), and port 8090 stays behind exe.dev login. For signups from the general public, use PocketBase's own users collection, with passwords or OAuth2, and set up SMTP (below). To close up again: ssh exe.dev share set-private my-pocketbase.

Email#

With no SMTP server set up, exe-email.pb.js sends PocketBase's email through exe.dev's email gateway, as plain text. The gateway only delivers to you, your exe.dev team, and people you've shared the VM with, and it's rate-limited: right for password resets and alerts to you, and fine while your users are your friends.

For email to anyone, turn on Settings → Mail settings → Use SMTP mail server and fill in your provider's details. The hook steps aside as soon as SMTP is on. Send test email, on the same page, tries whichever is in use.

Keep your data#

Everything PocketBase stores is in ~/pocketbase/pb_data: two SQLite databases and your uploaded files. Every night at 03:00 UTC PocketBase zips it into pb_data/backups and keeps the last seven. You'll find them in the dashboard under Settings → Backups, where you can also make one now, download one, restore one, or send them to an S3-compatible bucket.

Keep copies off the VM, too, with the encryption key in ~/pocketbase/pocketbase.env: without it, a restored backup can't read its own settings. On your computer:

scp my-pocketbase.exe.xyz:pocketbase/pocketbase.env .
scp 'my-pocketbase.exe.xyz:pocketbase/pb_data/backups/*.zip' .

Backups cover pb_data only. Your hooks, migrations, and pb_public live beside it: keep them in git. VM backups can save the whole VM to your own bucket.

The nuts and bolts#

Happy clicking Deploy? You can stop here. These are Shelley's setup steps and your maintenance reference.

Install by hand

Create a VM#

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

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

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

Download PocketBase#

This fetches a pinned release and checks it against PocketBase's checksums:

mkdir -p ~/pocketbase && cd ~/pocketbase
VERSION=0.42.3
zip=pocketbase_${VERSION}_linux_amd64.zip
url=https://ganigeorgiev.com/meta/pocketbase/pocketbase/download/v$VERSION
curl -fsSLO "$url/$zip" &&
curl -fsSL "$url/checksums.txt" | grep " $zip\$" | sha256sum -c - &&
unzip -oq "$zip" pocketbase && rm "$zip"
./pocketbase --version

You should see OK and pocketbase version 0.42.3.

Make a key and a superuser#

PocketBase encrypts its stored settings (SMTP and S3 passwords) with a key from the environment. pb runs PocketBase commands with that key and this data folder; the service uses it too.

cd ~/pocketbase
(umask 077; printf 'PB_ENCRYPTION_KEY=%s\n' "$(openssl rand -hex 16)" > pocketbase.env)
cat > pb <<'EOF'
#!/bin/sh
# Runs PocketBase with this install's data folder and encryption key.
set -a; . /home/exedev/pocketbase/pocketbase.env; set +a
exec /home/exedev/pocketbase/pocketbase --dir=/home/exedev/pocketbase/pb_data --encryptionEnv=PB_ENCRYPTION_KEY "$@"
EOF
chmod +x pb

email=$(curl -fsS https://reflection.int.exe.xyz/email | jq -r .email)
password=$(openssl rand -base64 18)
./pb superuser upsert "$email" "$password" &&
(umask 077; printf 'email: %s\npassword: %s\n' "$email" "$password" > superuser.txt)
chmod 700 pb_data
ls -l pocketbase.env superuser.txt

You should see Successfully saved superuser with your exe.dev email, and both files as -rw-------. reflection.int.exe.xyz is exe.dev's reflection integration; if it isn't available, set email to your exe.dev address yourself.

Add hooks, settings, and the notes page#

The hooks send email through exe.dev and keep superusers off the public port: read exe-email.pb.js and private-superusers.pb.js. The notes page is plain HTML and JavaScript. Two migrations set PocketBase up for this VM: its name and URL, real client IPs from exe.dev's X-Forwarded-For, the rate limiter, and nightly backups; then the notes collection.

cd ~/pocketbase
mkdir -p pb_hooks pb_migrations pb_public
for f in exe-email.pb.js private-superusers.pb.js; do
  curl -fsSL -o pb_hooks/$f https://exe.dev/deploy/pocketbase/$f
done
curl -fsSL -o pb_public/index.html https://exe.dev/deploy/pocketbase/index.html

now=$(date +%s)
cat > pb_migrations/${now}_exe_dev_settings.js <<EOF
/// <reference path="../pb_data/types.d.ts" />
migrate((app) => {
    const settings = app.settings()
    settings.meta.appName = "$(hostname)"
    settings.meta.appURL = "https://$(hostname).exe.xyz"
    settings.trustedProxy.headers = ["X-Forwarded-For"]
    settings.trustedProxy.useLeftmostIP = false
    settings.rateLimits.enabled = true
    settings.backups.cron = "0 3 * * *"
    settings.backups.cronMaxKeep = 7
    app.save(settings)
})
EOF

cat > pb_migrations/$((now + 1))_create_notes.js <<'EOF'
/// <reference path="../pb_data/types.d.ts" />
migrate((app) => {
    app.save(new Collection({
        type: "base",
        name: "notes",
        listRule: "",
        viewRule: "",
        createRule: "@request.headers.x_exedev_email != ''",
        fields: [
            { type: "text", name: "text", required: true, max: 500 },
            { type: "autodate", name: "created", onCreate: true },
        ],
    }))
}, (app) => {
    app.delete(app.findCollectionByNameOrId("notes"))
})
EOF
ls pb_hooks pb_migrations pb_public

PocketBase applies the migrations when it starts.

Run it with systemd#

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

[Service]
User=exedev
WorkingDirectory=/home/exedev/pocketbase
ExecStart=/home/exedev/pocketbase/pb serve --http=0.0.0.0:8090
Restart=always
RestartSec=5s
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now pocketbase
sleep 3
curl -fsS localhost:8090/api/health; echo

You should see {"message":"API is healthy.","code":200,"data":{}}. If not, journalctl -u pocketbase -n 30 says why.

Open the app port#

nginx answers on port 8000, the one https://$(hostname).exe.xyz/ reaches and the only one you can make public. It passes everything to PocketBase unbuffered, so realtime events flow, and marks each request with X-Public-Port for private-superusers.pb.js. Ubuntu's default nginx site also listens on 8000, so it goes.

sudo tee /etc/nginx/sites-available/pocketbase >/dev/null <<'EOF'
server {
    listen 8000;
    listen [::]:8000;
    client_max_body_size 0;

    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Public-Port 1;
        proxy_read_timeout 360s;
        proxy_buffering off;
        proxy_request_buffering off;
    }
}
EOF
sudo ln -sf /etc/nginx/sites-available/pocketbase /etc/nginx/sites-enabled/pocketbase
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl enable --now nginx && sudo systemctl reload nginx

Check both ports. The notes page answers on 8000, superuser sign-in is refused there, and on 8090 the right password signs in.

cd ~/pocketbase
curl -fsS localhost:8000/ | grep -o '<title>.*</title>'
email=$(sed -n 's/^email: //p' superuser.txt)
password=$(sed -n 's/^password: //p' superuser.txt)
for port in 8000 8090; do
  jq -n --arg i "$email" --arg p "$password" '{identity: $i, password: $p}' |
    curl -sS localhost:$port/api/collections/_superusers/auth-with-password \
      -H 'Content-Type: application/json' -d @- |
    jq -r --arg port "$port" '"\($port): " + (.message // "signed in")'
done
printf 'Dashboard: https://%s.exe.xyz:8090/_/\nApp:       https://%s.exe.xyz/\n' "$(hostname)" "$(hostname)"

You should see <title>PocketBase live notes</title>, then 8000: Superusers use the private port. and 8090: signed in. You're ready for the walkthrough above.

Back up and restore

To make a backup now, use Settings → Backups → Initialize new backup in the dashboard. Backups are zips of pb_data (without older backups), named like @auto_pb_backup_my_pocketbase_20261116030000.zip.

Restore on the same VM#

In Settings → Backups, pick a backup and choose Restore. PocketBase replaces pb_data, restarts, and is back in a few seconds.

Restore by hand, or on a new VM#

On a new VM, run Install by hand first, then replace its ~/pocketbase/pocketbase.env with the one from the old VM (the backup's settings need that key) and copy your hooks, migrations, and pb_public across. Copy the backup to ~/restore-me.zip, outside pb_data. On the VM, these commands set the current data aside rather than delete it:

cd ~/pocketbase
backup=~/restore-me.zip
unzip -tq "$backup" &&
sudo systemctl stop pocketbase &&
mv pb_data "pb_data.before-restore-$(date +%s)" &&
mkdir -m 700 pb_data &&
unzip -q "$backup" -d pb_data &&
sudo systemctl start pocketbase
sleep 3; curl -fsS localhost:8090/api/health; echo

Sign in to the dashboard with the superuser from the backup and check your data. If the VM's name changed, update Settings → Application URL.

Update

PocketBase is still before 1.0, so a release can change things your hooks rely on. Read the release notes first. Then, on the VM:

cd ~/pocketbase
./pb update && sudo systemctl restart pocketbase
sleep 3; ./pocketbase --version; curl -fsS localhost:8090/api/health; echo

update downloads the latest release, replaces the binary, and saves pb_data/backups/@update_v<version>.zip first. To pin a version instead, run Download PocketBase above with a different VERSION, then sudo systemctl restart pocketbase.

Use PocketBase as a Go framework

PocketBase is also a Go library: write your own main.go, add Go routes and hooks, and build a binary that replaces the prebuilt one. Go is already on the VM. main.go keeps your JS hooks and migrations working and adds /api/hello. On the VM:

mkdir -p ~/myapp && cd ~/myapp
curl -fsSLO https://exe.dev/deploy/pocketbase/main.go
go mod init myapp
go get ganigeorgiev.com/pocketbase/pocketbase@v0.42.3
go mod tidy
CGO_ENABLED=0 go build -o ~/pocketbase/pocketbase.new . &&
cp ~/pocketbase/pocketbase ~/pocketbase/pocketbase.prebuilt &&
mv ~/pocketbase/pocketbase.new ~/pocketbase/pocketbase &&
sudo systemctl restart pocketbase
sleep 3; curl -s localhost:8000/api/hello; echo

You should see {"hello":"stranger"}, or your email through https://my-pocketbase.exe.xyz/api/hello. To ship a change, run the go build, mv, and restart lines again. Your binary has no update command: update with go get ganigeorgiev.com/pocketbase/pocketbase@latest and a rebuild. To go back, move pocketbase.prebuilt into place. See Go for git push deploys, and PocketBase's Go docs.

Something's not happy?

Start with the logs. On the VM:

systemctl status pocketbase nginx --no-pager
journalctl -u pocketbase -n 50 --no-pager

The dashboard's Logs page shows each request, with hook errors.

  • No email? Check your spam folder and the Logs page for Sent email through exe.dev. The gateway only delivers to you, your team, and people you've shared the VM with.
  • Lost the password? In ~/pocketbase, run ./pb superuser update you@example.com 'a-new-password'.
  • Superusers use the private port. That's port 8000 doing its job. Use https://my-pocketbase.exe.xyz:8090/_/.
  • missing encryption key? Run commands through ./pb, not ./pocketbase. If pocketbase.env was lost, restore it from your copy: a new key can't read the old settings.
  • 502 Bad Gateway on the app URL? PocketBase is down or restarting; check its logs, and sudo nginx -t.
  • Realtime stops after a while? PocketBase closes idle connections after five minutes, and all of them after 30. The SDK reconnects; your own EventSource code must subscribe again on each PB_CONNECT.
  • 429 Too Many Requests? The rate limiter is on; tune it under Rate limiting in Settings.

Frequently asked questions#

Is PocketBase free?

Yes. PocketBase is open source under the MIT license. You pay only for your VM; see exe.dev pricing.

Why is the dashboard on port 8090 and not my main URL?

PocketBase serves its dashboard and API on one port. Ports other than the one you share always stay behind exe.dev login, so port 8090 holds the dashboard, and the port you can make public, 8000, refuses superusers outright. Even a leaked superuser password can't be tried from the internet.

Does PocketBase's realtime work through exe.dev's proxy?

Yes. Subscriptions use server-sent events, which pass through exe.dev's HTTPS proxy and the nginx on port 8000 without buffering. PocketBase ends a connection after five idle minutes, or 30 minutes in all; the JavaScript SDK reconnects and resubscribes by itself.

Where do PocketBase downloads come from now?

PocketBase moved off GitHub in October 2026; the GitHub repository is archived at v0.40.6. Releases, checksums, and the update command now use ganigeorgiev.com, and the Go module path is ganigeorgiev.com/pocketbase/pocketbase.

How do I use the JavaScript SDK?

npm install pocketbase, then new PocketBase("https://my-pocketbase.exe.xyz"). Call it from a page served by PocketBase (pb_public) or from a page on another domain once you share port 8000; requests from the browser carry the visitor's exe.dev sign-in.

Can I use my own domain?

Yes. Share port 8000, follow the custom domain guide, then change Application URL in the dashboard's Settings so links in emails point at it.

How big can a PocketBase app get on one VM?

PocketBase is one process with SQLite underneath, so it grows with the VM: more CPU, memory, and disk. That carries a lot of apps a long way. If you outgrow one machine, or need many writers at once, look at PostgreSQL.

Updated Nov 16, 2026 · tested end to end Nov 16, 2026 · Markdown · manifest.json · Something wrong? Tell us