Build with Palbase
Everything you need to ship with Palbase — the modules every project has, the web, server and backend SDKs, and the machines and databases that run your code.
Getting Started
Introduction
What Palbase is: the modules every project has — auth, storage, realtime, flags, notify, secrets, analytics, ai — and the machines and databases that run your own code.
Quickstart
Create a project in Studio, sign a user in from a web app, then put a backend on a machine from GitHub and call it.
Organizations
Organizations, projects and environments; members, invitations and the owner, admin and member roles; your Studio account's security; and the organization's audit log.
Architecture
How a palbase/backend app is shaped: a root module and one module per domain, thin controllers, services that arrive by constructor, schemas beside them, and the database declared in db/.
Project Structure
How a backend repository is laid out for a machine: src/main.ts, src/modules/<domain>/, src/db/, its Dockerfile, .env.example and tsconfig.json.
Access Tokens
Organization access tokens for CI and agents: PALBASE_TOKEN, the member and admin roles, what a token cannot do, expiry, and deleting one.
Billing
The Free plan and Pay as you go: the payment account and the organizations it pays for, charges at the month's end and at the threshold, what is charged, each project's plan and cap — its environments together — an environment's freeze, what happens when a charge goes unpaid, and the billing API.
Usage & Limits
What is metered for each environment and where Studio shows it, the rates and monthly limits it runs under, what a free project gets — its environments together — and what each limit answers.
Logs
Studio's Logs by category: every request to the environment's address, auth's events, notifications, machine output and builds — and the request lines read from a server.
CLI
Overview
palbase, the CLI in the npm package: signing in, choosing an environment, running a backend on your computer, tokens for CI and for AI agents, searching the docs by meaning, asking Palbase's support line, and what its commands cover.
Reference
Every command of the palbase CLI with its usage, what it does and its flags, as the CLI's own help prints them.
Backend SDK
Overview
palbase/backend — the framework your machine runs: PalbaseFactory, modules, class controllers, and the three things a handler imports — Palbase, Database and Log.
Modules & Dependency Injection
@Module's four lists, @Injectable providers, injection by constructor type, onStart and onShutdown, and the mistakes refused at boot by name.
Controllers & Routing
@Controller classes, the HTTP method decorators, route options (auth, rateLimit, transaction), path parameters, @Resolve — parameters the app makes — and what a handler's return becomes, a Response included.
Request Validation
@Body, @QueryParams, @Param and @Headers with any Standard Schema — zod, valibot, arktype — and the 400 a failed one answers.
Authentication
Secure-by-default routes, @User and @OptionalUser, verified email, test users, and how a caller's token is checked.
Responses & Errors
What a handler's answer becomes, the error envelope, the built-in error classes and PalError, and what an outage or a crash answers.
Database
Database — the request's own transaction: typed tables, raw SQL with $query, plans with $transaction, $atomic and $asService().
Schema
Your Postgres schema in TypeScript with defineSchema, defineTable, column builders, indexes, foreign keys and raw units.
Row-Level Security
Policies in the schema DSL, auth.uid(), the anon and authenticated roles, and $asService() for what the service does.
Field Encryption
text().encrypted(): a column sealed by your app with the project's keys — equality through a lookup, rows encrypted beside the serving release, key rotation, Studio's mask, and palbase/server's fields for any other server.
Encrypted Requests
encrypted() and encrypt(): a field the app seals before the request leaves the device and opens in the answer — keys and rotation, the errors, machines:call and Try it, and palbase/server's transit for any other server.
Schema changes
There are no migration files: a release migrates beside the version that serves — start, rollout, complete — with renamedFrom, fillWith and ignored for the changes that need them.
Storage
Palbase.storage — buckets, objects, public reads, signed URLs and image renditions, from your backend.
Direct Uploads
Files straight to storage: signed upload URLs your backend grants, and @Upload routes — storage asks the route where a file goes, then runs it with the stored object.
Secrets
The project's secrets: the set a machine is started with, and Palbase.secrets for values read while it runs.
Flags
Palbase.flags — define flags, give single users their own values, and read what a user sees, from your backend.
Notifications
Palbase.notify — email, push, SMS and WhatsApp, templates, topics, each user's preferences, when a message goes (their own hour, quiet hours, the marketing cap), audiences, İYS and stop texts.
Journeys
Messages, waits, branches and A/B splits a person goes through after what they did: the definition, Studio's flow editor and templates, a try on a test user, publishing, the report and journey.* events.
Realtime
Palbase.realtime — broadcast to a channel's subscribers and write its shared state from your backend.
Gateways
@Gateway — a realtime channel of the app: who may join, typed events, members' messages and their acks, the channel's moments, durable gateways that keep what they send, and pipes.
Channels
The realtime module's own channel declaration, for a backend that is not a palbase/backend app: who may join, publish and write state.
AI
Palbase.ai — one-shot answers, tools that run on your machine, agents defined at each turn, and chats your backend starts, which their members reach through a gateway.
AI on Your Own Machines
Runner pools of your own Macs and Linux machines: one type each, machines enrolled with palai and a single-use key, a chat started on a pool, the state your own loop scales by, cordon then delete — and the variables, secrets and setup script every session has.
Workspace Sync
A chat's workspace on a machine of yours, live and both ways with palai workspace sync and a workspace token; .palaisync; files your backend writes; conflicts and ai.workspace.conflict; what a tool sees of the workspace, and what it answers.
Webhooks
@Webhook — a third party's deliveries (Stripe, GitHub, Slack, …) at POST /webhooks/<name>, each signature checked before an @On of its event runs.
Event Hooks
@On — handle the platform's events (user.deleted, file.uploaded, …) in your backend, each delivery signed and run once.
Cron
@Cron — a provider the platform runs on a schedule (five fields of cron's, on a time zone's clocks), waking the machine for it; run now, paused and resumed from Studio and the CLI.
Tasks
@Task and Tasks.enqueue — work put on the machine's queue, done once, now or later: made again when it fails, failed tasks kept to try again, the machine asleep in between.
Cache
Cache — the project's short-lived entries, shared by every copy of a machine: get, set, getOrSet, incr and del, time to live, the quota, and what a call does when the cache is away.
Translations
t() — a sentence in the caller's language: palbase/strings/ kept with the code by `palbase strings`, missing translations from your AI module with --translate.
Test Users
Test users made with the secret key: what marks them, how to make and remove them, and user.test in a route.
Testing
Testing a backend: services as plain classes, and the app's whole HTTP layer through handle(), with no network.
Web SDK
Overview
palbase/web — createClient with the project's address and publishable key: what the client holds (auth, flags, analytics, consent, notify, purchases, the socket, your backend), its entry points, and what the project answers a browser.
Auth
Sign-up, sign-in, sessions, second factors, passkeys, magic links and phone codes in the browser.
Calling Your Backend
pb.<backend> — your machine's routes as typed calls from the module palbase apps:sync writes, the Vite plugin that builds each environment, BackendError, and CORS.
Error Handling
PalbaseError — status, code, request id and Retry-After — the retries the client makes, and the ones it never makes.
Uploads
Sending a file from the browser to storage: to your backend's upload route, or to a signed upload URL your backend made.
Flags
pb.flags — the project's flags and remote configuration for this reader, read without the network, kept current over realtime, with experiments' exposures.
Realtime
Channels over the project's one socket: join, listen to broadcasts, leave — and who may join what.
Messaging
pb.messaging — the person's conversations kept in IndexedDB and current over the socket: lists, timelines and threads to subscribe to, an outbox that sends once, files encrypted in the browser, and onIncoming for the page's own banner.
Calls
pb.calls — voice and video calls in the browser: making, answering and joining one, the session's state the app draws its own screens from, microphone, camera, screen sharing and audio output, a call at a place (pb.calls.place: watch, start, join unasked, PlaceBusyError), the media through the media server, ringing through the service worker, history, permissions and errors.
Gateways
Your backend's gateways from the generated module: join, typed events, messages and their acks, GatewayError's reasons, durable history, and a chat gateway's state.
Analytics
pb.analytics — events, page views, person properties and the browser's own measures, held to the person's consent — and the people, places and audiences the project reads back.
Consent
pb.consent — what the person allowed, key by key: the platform's keys, starting values, a consent screen, Global Privacy Control, and the calls under it.
Notifications
pb.notify — web push and its service worker, the signed-in person's inbox drawn ready, in-app messages shown in the page, and their preferences and topics.
Next.js
Next.js: palbase/web/ssr keeps the session in a cookie the browser and your server both read — the proxy, server components, route handlers — and palbase/server acts as the project.
iOS SDK
Overview
The iOS SDK in Swift: palbase-swift with Swift Package Manager, its products, iOS 18, registering the app, apps:sync and the Xcode build rule that compiles an environment in, PalbaseClient, the session in the keychain, errors and retries.
Auth
pb.auth in Swift: the observable sign-in state, email and password, guests, passkeys, Sign in with Apple and Google, second factors, magic links, phone codes, passwords and the user's sessions.
Calling Your Backend
The typed Swift client apps:sync generates for your backend: pb.<name>, request and response types, typed errors, BackendError, file uploads and untyped calls.
Gateways
Your backend's gateways from Swift: join, the Event, Send and Reply enums, PBGatewayError's reasons, durable history, and a chat gateway's PBChat for SwiftUI.
Realtime
pb.realtime: channels on the project's one socket, broadcasts, the state every member shares, presence, who may join, and the socket's observable status.
Messaging
PalbaseMessaging: @Observable conversations, timelines and threads, an outbox that sends once, incoming() for the app's own banner, and the notification service extension that brings a message onto the phone while the app is closed.
Calls
PalbaseCalls: calls that ring on the lock screen through CallKit and PushKit, configure(.init(callKit:)), the APNs key and the VoIP token, pb.calls.call/callGroup/join/history, the @Observable PBCall the app draws its own screens from (phase, cameras, shared screens, who is speaking, controls), screen sharing (in the app, or the whole screen through a Broadcast Upload Extension with PalbaseCallsBroadcast) and a call at a place (pb.calls.place).
Flags
pb.flags: feature flags read without waiting, observable in SwiftUI, kept current over realtime, a signed-in user's values, and experiments' $flag_exposure.
Analytics
pb.analytics: events, screens, the person's properties, the app's own events such as $install and $app_open, timings, diagnostics, and App Tracking Transparency.
Consent
pb.consent: the platform's keys and the app's own, starting values, the person's choices, region and needsAsking, and whose the choices are across sign-in and sign-out.
Notifications
pb.notify: APNs registration and push reports, preferences and topics, the notification service extension, the inbox, and in-app messages drawn in SwiftUI.
Storage
pb.storage: uploading and downloading at URLs your backend signs, a public bucket's objects, and what an upload answers.
Purchases
pb.purchases: what the customer has in any store, buying and restoring in the App Store, the published paywall drawn in SwiftUI, offers and codes, and web checkout from the app.
Voice
PBVoice from palbase-swift-voice: a chat's live voice over WebRTC, its offer through your backend, the audio session, muting and closing.
Debug Console
The in-app debug console: what the SDK and the app record on the device, pb.debug's calls, and the palbase.debug_console flag that opens it for one user.
Android SDK
Overview
The Android SDK: the studio.palbase Maven repository and BOM, minSdk 26 and Kotlin 2.2, registering the app, apps:sync and the build step that compiles an environment in, PalbaseClient, and its errors and retries.
Auth
pb.auth on Android: sign-up and sign-in, guests, second factors, magic links, phone codes, passwords, the observable session bound to the device, signing out and deleting the account.
Calling Your Backend
The Kotlin client apps:sync generates from your backend's contract: pb.<name>, a typed function per route, its typed errors and BackendError, retries, uploads and a backend on your computer.
Gateways
A backend's @Gateway classes from the generated Kotlin client: join, typed events, messages and their acks, PBGatewayError, durable gateways, and a chat gateway's state in Compose.
Realtime
pb.realtime channels on Android: broadcasts, a shared state and presence, who may join, and the one socket's connection as a StateFlow.
Messaging
palbase-messaging: conversations, timelines and threads as StateFlows, an outbox that sends once, incoming for the app's own banner, pushes that bring a message onto the phone while the app is closed, and FLAG_SECURE for what is seen once.
Calls
palbase-calls: a ring over the lock screen from a high-priority FCM message, CallStyle and Telecom, the permissions and canRingFullScreen, pb.calls.call/callGroup/join/open/history/current, PBCall's StateFlows and actions the app draws its own screens from, the app's own call activity over the lock screen (pb.calls.callActivity), screen sharing (MediaProjection) and a call at a place (pb.calls.place).
Flags
pb.flags on Android: values read without waiting from what the device kept, typed reads, Compose state, per-user values, and live updates over the socket.
Analytics
pb.analytics on Android: events, screens, timings and diagnostics, each behind its consent category, batched and kept on the device until sent.
Notifications
FCM push on Android: the project's FCM provider, pb.notify.register for the signed-in user, showing the data message a push arrives as, preferences and topics.
Storage
pb.storage on Android: uploading and downloading through URLs your backend signed, and reading public buckets.
Purchases
pb.purchases on Android: what the customer has in any store, kept current, and buying on Google Play with Play Billing: products, purchase, plan changes, restore and web purchase links.
Voice
PBVoice: a chat's live voice over WebRTC on Android, its offer through your backend, the microphone permission, the device's audio, mute and close.
Debug Console
What the Android SDK records on the device from launch, what the app adds to it, and PalbaseConsole: the in-app console the project opens for one user with a flag.
Server SDK
Auth
Overview
An environment's auth, set up from Studio, the CLI or the admin calls: passwords, email confirmation, email links, sessions and token lifetimes, passkeys, risk, security emails, signing keys and auth's own emails.
Sign-in Providers
Turning on email, phone, Google, Apple, GitHub and Microsoft sign-in — each provider's clients, secrets and callback URL — and guest accounts.
Users & Roles
The environment's users: finding, creating, banning, signing out, deleting and exporting them; their sessions; application roles; and importing users with their passwords and sessions.
Blocking Hooks
An endpoint of yours that auth calls and waits for before a sign-up, a sign-in or a token: the events, the signed request and answer, timeouts and failure modes.
Audit Trail
Who did what in an environment's auth — sign-ins, changes to users and settings, admin actions — read, exported as JSON lines or CSV, and verified as an unbroken chain.
OpenID Provider
Other apps signing in with your users' accounts through the environment's OAuth 2.0 and OpenID Connect provider, service accounts for machines, and sign-in tokens your own server makes.
Purchases
Overview
One catalog sold in the App Store, on Google Play and on the web through your Stripe account, and one answer to what each customer has: products, plans, entitlements, credits, limits, the stores and test purchases.
Catalog
The catalog as a JSON document in revisions: products, plans, prices, channels and what each gives; purchases:catalog:get, validate and put, and the plan that writes it to Stripe, App Store Connect and Google Play once confirmed.
App Store
Selling in the App Store: the App Store Connect API key and the In-App Purchase key, server notifications, purchases:doctor, and how each StoreKit transaction is verified, owned, restored and refunded.
Test Apple Purchases
Buying the catalog's iOS products before anyone pays: in Xcode from a StoreKit file made from the catalog, then in the App Store sandbox with a tester — and the app's and the server's code for both.
Google Play
Selling on Google Play: the service account your Play Console invites, the real-time developer notifications topic, and how each Play purchase is read, owned, acknowledged and refunded.
Connect Stripe
The environment's own Stripe account sells the catalog on the web: connected with one click through Palbase's Stripe App, or with a restricted key.
Web
Selling on the web with pb.purchases: offerings, Stripe Checkout, buyers with no account and their redemption links, what the customer has, the customer portal, a paywall in the page, and web checkout from an iOS app.
Paywalls
Paywalls designed once and drawn natively, published without an app update: the definition, drafts and versions, assets, placements and their targeting rules, and experiments that say which sells best.
Offers & Coupons
Discounts, free trials and grants for an audience or everyone, once a customer, sold as each store's own offer; and coupons: shared or one-time codes, and App Store offer codes.
Entitlements, Credits & Limits
CustomerInfo and isEntitled on your server; credits spent in one step or held with withReservation; quotas in windows with overflow; and the purchases events your backend receives.
Customers
Looking a customer up, giving and revoking entitlements, guests whose purchases move to the account they sign in to, restores, deleted users, and the purchase settings.
Charts
Revenue, MRR, subscriptions, conversion, LTV and retention from the ledger: purchases:charts, segments and filters, revenue types, CSV, and the reporting currency and fees.
Calls
Overview
Voice and video calls between a project's people: direct calls device to device with a relay to fall back on, groups of up to 100 on the media server, huddles; who may call whom, a call's life from ring to end, history, settings and prices.
Calls over HTTP
What the SDKs send for a person's device: making, answering, declining, joining and leaving a call, the heartbeat, the media (ICE servers or a media-server ticket), a direct call's signals, the calls:<ref>:<user_id> channel and the call's shape.
Ringing
How a call rings a locked phone: a PushKit VoIP push and CallKit on iOS, a high-priority data message and a full-screen CallStyle notification on Android, a notification in a browser; missed calls, and what each push carries.
Your Server
The secret key's calls: the module's settings, the calls.can_call hook that decides who may call whom and its signature, reading and ending the project's calls, and the calls.* webhooks.
Agents
Letting your own agent into a call with a ticket: the media server's url and token, each speaker's audio as a track named by their user id, publishing its own voice, and when to send it in.
Analytics
Overview
What a project's analytics keeps — events, people, performance samples, request traces, console history — whose each one is, consent, how long it is kept, and its limits.
Reading Analytics
Studio's Analytics screens, and the secret key's reads: summaries, event lists and timelines, breakdowns, funnels and retention, from a server or the CLI.
Performance
Web vitals, app starts, network and custom samples; the requests your apps and backend report; and a device's debug history — in Studio and from a server.
Client Apps
Client Apps
Registering a project's iOS, Android and web apps with the CLI: what each is in an environment, its own publishable key, the passkey association files the environment publishes from it, and deleting and restoring one.
Syncing an App's Settings
What palbase apps:sync writes under palbase/ in an app's repository — each environment's settings, its publishable key and its backends' typed clients — how a build picks its environment, and checking it in CI.
App Distribution
App Distribution
Builds from your build machine to TestFlight and Google Play's internal testing: packages and build numbers, deliveries and their states, the actions a person confirms, Studio's screens and the stores events.
TestFlight
An iOS app's builds to TestFlight with your own Apple account: connecting an App Store Connect key, the unsigned .ipa and its entitlements, signing, groups and testers, Beta App Review and export compliance.
App Store
An iOS app's App Store page and the version App Review gets: the draft page and its screenshots, planned and confirmed; preparing the version, what is missing, sending it to App Review, releasing it, the phased release, and App Review's answer.
Google Play
An Android app's builds to Google Play's internal testing: the service account Play Console invites, the upload key Palbase signs with, the .aab and its version code, and the first release made in Play Console.
App Health
Each linked app in its store: the App Store Connect webhook Palbase makes and the key role it needs, the events it tells and their source, testers' crashes and screenshots, the App Store's crash data and Play's vitals, and Play's releases read every 10 minutes.
Machines & Databases
Machines
Your own code on Palbase: a machine's size, sleep and wake, its address and port, health check, copies, environment, secrets, crons and tasks.
Connecting GitHub
The Palbase Cloud GitHub App, a machine's repository, branch and directory, and which pushes build which machines.
Builds, Logs & Rollback
What a push does: the build, the settings .env.example asks for, the rollout beside what serves, the logs, and returning to an earlier build.
Databases
Postgres of your own: sizes, the passwords shown once, the owner and app logins, direct and pooled addresses, who may connect, a machine's database, and the SQL console.
Sites, Previews & Domains
Static sites deployed from a folder or built from GitHub, releases and rollback, pull request previews, your own domain, and keeping a machine awake.
Backups & Restore
Backups kept for the days you choose, bringing a database back to a moment, and deleting, taking back and purging one.