Get started
Local development
Tested with:Databasezy API v1 · zb CLI 0.1
zb start runs a whole Databasezy project in Docker on your machine: Postgres plus auth, the Data API,
storage, realtime and Functions, behind the same project gateway the hosted platform uses. It needs no
account, API key, organization or cloud project, and nothing is sent to the Databasezy API. Each project
directory gets its own containers, network, data volume, keys and certificate, so several projects run
side by side.
Requirements
Section titled “Requirements”-
Docker Engine 28 or newer (Docker Desktop on macOS and Windows) with the Compose v2 plugin. The Docker context must be local - a Unix socket, a Windows named pipe or a loopback TCP endpoint; remote contexts are refused. If the daemon is not running,
zb startstops with exit code6andthe Docker daemon is not respondingafter at most 15 seconds, without creating anything. -
The service images.
zb startpulls missing images (--pull neverforbids it):Container Image postgresdocker.io/library/postgres:17.6-alpineauthghcr.io/zerobase/app-auth:<tag>postgrest(Data API)docker.io/postgrest/postgrest:v16.4- the platform’s pinned PostgRESTstorageghcr.io/zerobase/storage:<tag>object-storedocker.io/rustfs/rustfs:1.0.3realtimeghcr.io/zerobase/realtime:<tag>functionsghcr.io/zerobase/functions:<tag>functions-runtimeghcr.io/supabase/edge-runtime:v1.77.4- the platform’s pinned runtimegatewayghcr.io/zerobase/gateway:<tag>A development build of
zbuses the tagdev: build those five images from a checkout of the repository withscripts/build-go-image.sh --tag dev app-auth storage realtime functions gateway. A release build usesmain.--image-tag <tag>picks another tag and--image <container>=<reference>replaces one image.
Start a project
Section titled “Start a project”-
Mark an existing directory as a local project. This writes
.databasezy/local.json(an id, nothing secret).shell zb init --dir ./my-appcd my-app -
Start it. The first start pulls images, creates the database and bootstraps the auth, storage and realtime schemas and roles, which takes a few minutes; later starts take seconds.
shell zb startoutput Local project: 3f9c... (prj_01k...)Directory: /home/me/my-appState: runningpostgres runningauth runningdata-api runningstorage runningrealtime runningfunctions runningAPI URL: https://localhost:52417CA certificate: /home/me/.config/databasezy/local-projects/<hash>/platform/tls/ca.crt (trust it in your client; the OS trust store is not changed)Database URL: postgresql://app:<redacted>@127.0.0.1:55124/app?sslmode=disableEnv file: /home/me/.config/databasezy/local-projects/<hash>/local.env (keys and passwords, owner-only; never printed)Volume: zb-local-3f9c...-data (retained by stop) -
Load the env file into your app or shell and use the API URL with any Supabase client.
shell set -a; . "$(zb status --json | jq -r .env_file)"; set +acurl --cacert "$DATABASEZY_CA_FILE" -H "apikey: $DATABASEZY_PUBLISHABLE_KEY" "$DATABASEZY_URL/auth/v1/settings" -
Stop it when you are done. Data is kept; the next
zb startbrings it back.shell zb stop
Services
Section titled “Services”Every service except the database is reached through the gateway at https://localhost:<port>, with the
same paths as a hosted project:
| Service | --services name | Path | Runs |
|---|---|---|---|
| Postgres | postgres | 127.0.0.1:<port> (DATABASEZY_DB_URL) | Postgres 17.6 with logical replication |
| Auth | auth | /auth/v1 | the platform’s auth service |
| Data API | data-api | /rest/v1 | PostgREST, schema public, roles anon / authenticated / service_role |
| Storage | storage | /storage/v1 | the platform’s storage service on a local S3 object store |
| Realtime | realtime | /realtime/v1 | the platform’s realtime service (broadcast, presence, Postgres changes) |
| Functions | functions | /functions/v1/<name> | the platform’s Functions host and edge-runtime |
zb start runs all six. --services picks a subset - a comma-separated list, or all; Postgres is always
included and any other service also starts the gateway:
zb start --services data-api,auth # the database, PostgREST, auth and the gatewayzb start # the rest joins; nothing is recreatedzb start --services postgres in a new directory runs only a database: no gateway, no TLS, no keys. That
directory keeps the Postgres-only runtime - its database is created without the platform’s logical
replication settings and is never recreated - so zb start there keeps starting just Postgres, and asking for
other services is refused. Use a new directory for the full stack.
Only two ports are published, both on 127.0.0.1 alone: the gateway’s and the database’s. The gateway port is
a free port chosen at the first start (or --port) and stays the project’s port; if another process holds
it, zb start refuses before creating or starting anything. The database port is assigned by Docker at each
start; the env file is rewritten every time.
Keys, the env file and TLS
Section titled “Keys, the env file and TLS”Each project generates its own keys at the first start and never rotates them: a publishable and a secret
project key, anon and service-role JWTs (valid for a year), an ES256 signing key,
database role passwords and a certificate authority for the gateway’s certificate. They live in private state
under the OS configuration directory - not in the project directory, so they cannot be committed by
accident - and zb start writes the ones your app needs to local.env there (mode 0600):
| Variable | Value |
|---|---|
DATABASEZY_URL | https://localhost:<port> |
DATABASEZY_PUBLISHABLE_KEY / DATABASEZY_SECRET_KEY | the project keys (zbp_... / zbs_...) |
DATABASEZY_ANON_KEY / DATABASEZY_SERVICE_ROLE_KEY | legacy JWTs for clients that expect Supabase’s anon and service-role keys |
DATABASEZY_DB_URL | the database URL with its password |
DATABASEZY_CA_FILE, NODE_EXTRA_CA_CERTS | the project’s CA certificate |
Keys are never printed. zb status --show-secrets adds only the database password to the database URL. The
URL and key variables are the ones the SDK compatibility suite
reads; scripts/sdk-compat/run.py --local <dir> runs it against a local project.
The gateway serves TLS with a certificate for localhost signed by the project’s own CA. Trust that CA in
your client - Node reads NODE_EXTRA_CA_CERTS, curl takes --cacert, Deno takes --cert - rather than
turning verification off. zb does not add it to your operating system’s trust store.
No email is sent locally, so new users are confirmed when they sign up. Redirects go to --site-url
(default http://localhost:3000), which, like the gateway port, is fixed at the first start.
Functions
Section titled “Functions”Each directory under supabase/functions (or functions) is a function, as for
zb functions deploy: zb start bundles them with the same bundler and serves them at
/functions/v1/<name>. verify_jwt comes from supabase/config.toml and is on by default. There is no hot
reload: run zb start again after editing a function; unchanged functions keep their version, a deleted
directory stops serving its function.
Stop, restart and data
Section titled “Stop, restart and data”zb stop stops the services first and the database last. Containers, the network, the database volume and
the object store are kept, and the CLI never deletes any of them. zb start on a running project changes
nothing. zb status shows each service’s state, the URLs and the env file path; --json prints the same as
JSON.
Images are pinned by their image ID at the first start. If one is removed, zb start pulls it back only when
its tag still points at the same image; a project never silently moves to other images - start a new
directory for newer ones.
To delete a project’s data, remove its Docker objects yourself - the containers labelled
com.databasezy.local.project=<id>, the volume zb-local-<id>-data and the network zb-local-<id>-network,
where <id> is the id in .databasezy/local.json - and then the project’s directory under
databasezy/local-projects in your OS configuration directory.
Differences from a hosted project
Section titled “Differences from a hosted project”- One realtime replica with an in-memory bus, and the Free plan’s limits.
- Stock Postgres 17.6: the hosted extension set and GraphQL (
pg_graphql) are not available. - No email delivery, and nothing is metered or billed.
- Functions run without the hosted sandbox (gVisor/Kata) and are invoked over HTTP; triggers (cron, database, storage, auth, queue) are not set up locally.
- The gateway certificate and the legacy JWTs are valid for a year and are not renewed automatically.
Commands
Section titled “Commands”| Command | What it does |
|---|---|
zb init [--dir DIR] | Marks an existing directory as a local project. |
zb start [--services LIST] [--port N] [--site-url URL] [--image-tag TAG] [--image C=REF] [--pull missing|never] [--timeout 10m] | Starts the stack (or a subset) and writes the env file. --timeout accepts 1s to 15m. |
zb status [--show-secrets] [--json] | Shows each service, the API URL, the CA and env file paths. |
zb stop [--timeout 2m] | Stops everything and keeps all data. |
Every command takes --dir (default .). Full flag reference: CLI reference.