Skip to content

Deploying a Backend

Backends let you run arbitrary server-side code next to your PocketBase instance — REST APIs, webhook handlers, background workers, or a full Next.js app. Each backend runs in its own container with HTTPS and a dedicated subdomain.

Note: backend deployments require the Pro plan.

Supported runtimes

  • Node.js — the standard JavaScript runtime
  • Deno — TypeScript out of the box
  • Bun — fast all-in-one runtime
  • Next.js — deploy a full Next.js application with server-side rendering
  • Python — Flask, Django, FastAPI, and other frameworks, or a plain script. See Deploying a Python App

Deploying a Next.js app

A Next.js app with server-side rendering or API routes deploys as a backend. pbc deploy detects next.config.*, adds output: "standalone", runs the build, and ships the standalone bundle for you — the mechanics are in What gets packaged below. An app configured with output: "export" is a static site and deploys as a frontend instead.

Step 1: Prepare your app

Your app must listen on the port provided in the PORT environment variable — PocketBase Cloud injects it automatically:

// Node.js / Bun
const port = process.env.PORT || 3000;
app.listen(port);
// Deno
Deno.serve({ port: Number(Deno.env.get("PORT")) || 3000 }, handler);

Python apps get a start command that already listens on PORT. See Deploying a Python App.

Step 2: Deploy

Using the portal

  1. Open your project and go to the Backends tab
  2. Click New Backend — the name is auto-generated, edit it if you like
  3. Drag your project files, folders, or a ready-made ZIP into the upload area (source files, package.json, lockfile — node_modules is not needed; dependencies install during deployment)
  4. Review the file list — the detected runtime and start command are shown — and click Create. The first deploy ships with creation

Re-deploying is the same dialog from the backend’s detail page: drop new files and click Deploy, and the container is replaced with the new version. Every deploy is recorded in the Deployments list.

To override the runtime, port or start command, open the backend’s Settings page and edit Runtime. Changes apply on the next deploy, which detects the runtime again; leave the start command blank to detect it.

Using the CLI

cd api
pbc backend deploy --name my-app-api

One command builds, packages, uploads, creates the backend if needed, pushes a neighbouring .env, and waits for the container to reach running.

pbc deploy --name my-app-api does the same: a deno.json, a server dependency such as express or hono, a start script, or a next.config.* without output: "export", or a Python dependency file or script all identify a backend. See One deploy command for all three.

The first deploy records the backend in api/pbc.json, so afterwards:

pbc backend deploy    # redeploy the linked backend

The runtime, build command, and start command are inferred from the directory (deno.json, bun.lockb, next.config.*, package.json, or a Python project) and written into pbc.json. Review the guess before shipping with pbc init backend:

// api/pbc.json
{
  "projectId": "dhs4xnprgplurvo",
  "kind": "backends",
  "defaultEnvironment": "production",
  "environments": {
    "production": { "id": "…", "name": "my-app-api" }
  },
  "build": {
    "runtime": "nodejs",
    "startCommand": "node index.js"
  }
}

Useful flags:

Flag What it does
--name <name> Which backend to deploy. Asked for when omitted and nothing is linked.
--runtime <deno|bun|nodejs|nextjs|python> Overrides build.runtime
--python-version <3.10…3.14> Python version for this deploy; detected from the project when omitted
--start <cmd> The command that boots the container
--compute <id> Compute to deploy onto. Asked for when the project owner has more than one — list them with pbc compute ls. (Formerly --server, still accepted.)
--skip-build Package without running the build command
--skip-env Don’t push the neighbouring .env
--zip <file> Upload an archive you built yourself
--env <name> Which pbc.json environment to target

What gets packaged

deno, bun, nodejs, and python ship their source — the platform installs dependencies on start, so node_modules and Python virtualenvs are excluded from the archive.

nextjs is different: the platform does not run next build (it exhausts memory on a shared host), so you ship a prebuilt bundle. That bundle exists only when the build asks for it, so the CLI adds output: "standalone" to next.config.* for you — before the build runs, printing the change — and writes a next.config.js if the project has none. A config that already sets output is left as it is. The CLI then assembles .next/standalone, .next/static, and public into the layout the runtime expects, starting it with node server.js:

// api/pbc.json
{
  "build": { "command": "npm run build", "runtime": "nextjs" }
}

A config setting output: "export" is refused rather than rewritten — that is a static site, not a server, so deploy it as a frontend instead.

Uploading a Next.js ZIP by hand in the portal requires assembling that same layout yourself, which is the main reason to prefer the CLI for Next.js.

Your backend is live

Once the status turns running, your backend is live at:

https://<backend-name>.pocketbasecloud.com

Watch for that status on the Backends tab in the portal, or from the terminal:

pbc backend ls
pbc backend info --name my-app-api

Step 3: Connect to your PocketBase instance

Backends talk to PocketBase over its public URL like any other client, but with server-side credentials kept in environment variables. Every backend gets its project’s PocketBase URL as POCKETBASE_URL on every deploy, and a copy in a preview or environment gets that environment’s PocketBase. Its Variables page shows it under From PocketBase; set the variable yourself to point somewhere else:

import PocketBase from "pocketbase";

const pb = new PocketBase(process.env.POCKETBASE_URL);
await pb
  .collection("_superusers")
  .authWithPassword(process.env.PB_ADMIN_EMAIL, process.env.PB_ADMIN_PASSWORD);

Viewing logs

Using the portal

The backend’s Logs page streams your container’s stdout/stderr in real time.

Using the CLI

pbc logs backend --name my-app-api            # last 50 lines
pbc logs backend --name my-app-api --lines 500
pbc logs backend --name my-app-api -f         # follow

Either way, the most common cause of a crash loop is listening on a hard-coded port instead of process.env.PORT.

Rolling back

When a deploy breaks something, put the backend back on an earlier successful deployment. Its build goes live again as a new deployment, so nothing is deleted and you can roll forward the same way. The last 20 successful builds of each backend are kept for this. Environment variables are not part of the build: a rollback restores the code and keeps the variables as they are now.

Using the portal

  1. Open the backend — the Deployments list is on its detail page
  2. Click Roll back on the deployment to return to
  3. Check the build’s date and commit in the dialog and click Roll Back

For a backend connected to GitHub, the dialog links the comparison of what the rollback undoes.

For a backend that deploys from GitHub on every push, the rollback leaves the repository alone unless you tick Also put the source in … back in the dialog (--push-to-git with the CLI, pushToGit for an AI assistant). Then the backend’s root directory is put back as it was at the old build’s commit, so the next push keeps the rollback. When the branch has commits that were not deployed yet, or Review changes made in PocketBase Cloud is on in the repository settings, a pull request is opened instead; merge it to keep the rollback. Without it, the next push to the branch deploys over the rollback.

Each deployment in the list shows who deployed it (you, a teammate, or the commit’s author for a GitHub push), how, and the commit; its … menu opens the commit on GitHub.

Using the CLI

pbc backend deployments            # recent deployments, the live one marked
pbc backend rollback               # back to the success before the live one
pbc backend rollback --to <id>     # back to a specific deployment

rollback asks for confirmation; pass --yes in scripts. An AI assistant connected through the MCP server does the same with rollback_deployment.

Deleting a backend

Using the portal

Open the backend, go to its Delete page, and confirm.

Using the CLI

pbc backend rm --name my-app-api          # asks for confirmation
pbc backend rm --name my-app-api --yes    # scripted

Next steps

Framework guides