Skip to content
DocsBackendBackend Environment Variables

Environment Variables

Backends read their configuration — PocketBase URLs, API keys, third-party secrets — from environment variables. PocketBase Cloud stores them encrypted at rest and injects them into your container at startup, so secrets never live in your code or your ZIP archive.

Adding variables

Using the portal

  1. Open your backend and go to the Env Vars page
  2. Click Add Variable, enter a key and value
  3. Save

You can also paste an entire .env file to set many variables at once — each KEY=value line becomes one variable.

Using the CLI

pb cloud env set STRIPE_SECRET_KEY=sk_live_… --target backend --name my-app-api
pb cloud env ls --target backend --name my-app-api
pb cloud env rm STRIPE_SECRET_KEY --target backend --name my-app-api

Bulk-import a dotenv file:

pb cloud env import .env.production --target backend --name my-app-api

Inside a linked directory the --name is optional, and --env picks a non-default environment:

cd api
pb cloud env ls --target backend
pb cloud env set API_KEY=… --target backend --env staging

env ls prints names only — the platform stores values encrypted and its list endpoint never returns plaintext, so there is nothing for the CLI to show. Read a value from the app itself, or overwrite it with env set.

Pushed automatically on deploy

A .env file sitting next to pb.json is pushed to the backend on every deploy. Keys in the file are written; keys that exist only in the cloud are left alone. The values are never printed, and the file itself never goes into the ZIP:

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

This is usually all you need — env set is for one-off changes and for secrets you don’t keep on disk.

Using variables in your code

Variables are available through the standard runtime APIs:

// Node.js / Bun / Next.js
const apiKey = process.env.STRIPE_SECRET_KEY;
// Deno
const apiKey = Deno.env.get("STRIPE_SECRET_KEY");

Applying changes

Environment variables are injected when the container starts, so after adding or changing them the backend has to be redeployed for the new values to take effect.

Using the portal

Re-upload the current ZIP on the backend’s Deploy page.

Using the CLI

pb cloud backend deploy

Reserved variables

PocketBase Cloud manages a few variables for you:

  • PORT — the port your app must listen on. Don’t override it; read it and bind to it.

Deployments created from a template also come pre-configured with POCKETBASE_URL, ENV, and CORS settings pointing at the template’s PocketBase instance.

Security notes

  • Values are encrypted at rest and only decrypted when your container starts
  • Values are write-only — in the portal and in pb cloud env ls alike. Treat them like a password manager entry and keep a copy of anything you can’t regenerate
  • Keep .env files out of version control; the CLI never packages them into a deployment archive, but Git will happily commit them
  • Prefer environment variables over committing secrets to your repository, even for “temporary” testing

Next steps

Previous← Deploying a BackendNextDeploying a Frontend →