Local Development

There are two ways to build on PocketBase Cloud, and both are supported all the way to production:

• In the portal — deploy an instance first and edit collections, API rules, and hooks in its admin panel. Nothing to install; changes are live immediately.
• On your machine — run PocketBase locally with the pbc CLI, keep your schema and hooks in Git, and deploy the directory when it’s ready. Slower to start, but you get version control, offline work, and repeatable deploys.

Most teams use both: the portal to try something, the local project as the source of truth.

Using the portal

Deploy an instance (Deploying PocketBase), then work directly in its admin panel at https://<your-instance>.pocketbasecloud.com/_/:

1. Create collections and fields under Collections
2. Set API rules from the lock icon on each collection
3. Add server-side logic from the instance’s Hooks tab in the portal
4. Point your app at the instance URL and start building

This is the shortest path to a working backend. Its trade-off is that the schema lives only on that instance — export it (Settings → Export collections, or pbc admin collections export) if you want it in your repository.

Using the CLI

Step 1: Scaffold a local project

mkdir db && cd db
pbc local init

pbc local init downloads the PocketBase binary for your OS and CPU, then creates:

Existing files are never overwritten, so it’s safe to run in a directory that already has code.

Step 2: Run it

./pocketbase serve

The admin UI is at http://127.0.0.1:8090/_/ and the REST API at http://127.0.0.1:8090/api/. On the first run PocketBase prints a one-time link for creating your superuser account.

Step 3: Build your schema

Use the local admin UI, or drive the local instance with the same CLI commands you’d use against a deployed one:

pbc admin use http://127.0.0.1:8090
pbc admin login
pbc admin collections create '{"name":"posts","fields":[
  {"name":"title","type":"text","required":true},
  {"name":"body","type":"editor"}]}'
pbc admin rules set posts --list-rule '@request.auth.id != ""'

PocketBase writes a migration file into pb_migrations/ for every schema change you make locally, so committing that directory keeps your schema in Git.

Step 4: Write hooks

Hook files are plain JavaScript in pb_hooks/, named *.pb.js. The instance reloads them automatically when you save:

// pb_hooks/main.pb.js
routerAdd("GET", "/api/hello/{name}", (e) => {
  return e.json(200, { message: `Hello ${e.request.pathValue("name")}!` });
});

See Extending with Hooks for the full API.

Step 5: Deploy the same directory

pbc login
pbc project create my-app
pbc project use my-app
pbc pocketbase deploy --name my-app-db

The first deploy packages pb_public, pb_hooks, and pb_migrations and ships them with the new instance — your local schema and hooks are applied on creation. It also links the directory, so later redeploys are just:

pbc pocketbase deploy

Note: a redeploy ships all three again. pb_hooks/*.pb.js go through the hooks route, and the archive’s pb_migrations and pb_public are installed on the running instance — migrations are merged with the ones already there (nothing is deleted) and pb_public is replaced wholesale. New migrations run on the restart that follows. Schema changes made in the instance’s admin panel or through pbc admin collections keep working alongside this.

Pinning the PocketBase version

pbc local init records the version it installed in pbc.json, and deploys use that pin — so your cloud instance runs the same build you developed against.

pbc local versions            # list available releases
pbc local install 0.39.9      # switch this directory's binary and update the pin
pbc local which               # show the installed binary and its pin

Override it for one deploy with pbc pocketbase deploy --pb-version 0.39.9. With no pin and no flag, deploys use the newest published release.

A fresh clone has no binary (it’s git-ignored) — pbc local init in the clone installs the pinned version.

Frontends and backends

The same pattern applies to the rest of your stack: one directory per resource, each bound by its own pbc.json, all in the same project.

cd ../web  && npm run dev                      # develop however you normally do
pbc frontend deploy --name my-app-web

cd ../api  && npm run dev
pbc backend deploy --name my-app-api      # Pro plan only

deploy infers how to build and package each directory (build command, output directory, backend runtime) and records the guess in that directory’s pbc.json. Run pbc init to produce that block on its own and review it before anything ships:

cd web
pbc init frontend    # writes the build block, touches nothing in the cloud

Edit the block whenever the guess is wrong — it is never overwritten.

Environment variables

A .env beside pbc.json is pushed to the PocketBase instance or backend it belongs to on every deploy. Keys in the file are written; keys that exist only in the cloud are left alone. Values are never printed, and the file itself never goes into the ZIP.

pbc backend deploy                      # pushes .env
pbc backend deploy --skip-env           # leaves cloud env vars alone
pbc backend deploy --env-file .env.prod # pushes a different file

Frontends have no cloud env store — their variables are baked in at build time.

Next steps

• Deploy a PocketBase instance
• Extend your instance with hooks
• Manage your instance