Self-host PocketBase
A whole backend in one file, on a disk that stays put.
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/stdinPocketBase 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
https://my-pocketbase.exe.xyz:8090/_/
The dashboard and the full API, for you
https://my-pocketbase.exe.xyz/
Your app and its API; public once you share it, superusers refused
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/stdinWhat 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.
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. Usehttps://my-pocketbase.exe.xyz:8090/_/.missing encryption key? Run commands through./pb, not./pocketbase. Ifpocketbase.envwas 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
EventSourcecode must subscribe again on eachPB_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