Configuration — ZigBase

ZigBase is configured by environment variables and a small set of serve command-line flags.

Precedence

Configuration resolves in order of increasing precedence:

1. Built-in defaults
2. Environment variables
3. serve command-line flags (where a flag exists)

So a flag overrides the matching environment variable, which overrides the default.

CLI commands

Offline storage maintenance

Build with -Dfile-inventory=true to include zigbase files reconcile. It emits JSON and defaults to a read-only preview; built-in local storage plus SQLite is required in both modes. S3/PostgreSQL/custom backends are refused.

Apply refuses cooperating running apps, including serve --ignore-lock. Stop older/external writers yourself and keep the root dedicated to one database. Every built-in local-storage app holds one boot-lifetime maintenance descriptor, even without this CLI enabled; never remove its permanent lock file. Age alone does not prove an upload has finished. See offline reconciliation for retained unknown metadata, pagination bounds and partial-failure semantics.

Server and common commands

zigbase serve [--http-host H] [--http-port N] [--data-dir PATH] [--serve-static DIR]
              [--insecure-cookies] [--trust-proxy] [--realtime-origins CSV]
              [--background] [--ephemeral] [--ignore-lock] [--force]
zigbase serve stop | status [--json] | logs [--follow] [--data-dir PATH]
zigbase doctor [--production] [--json] [--data-dir PATH]
zigbase migrate [--data-dir PATH]
zigbase superuser create --email E --password P [--data-dir PATH]
zigbase version
zigbase help

Running zigbase with no recognised command prints usage.

• serve — start the HTTP server. The --serve-static DIR flag enables static file serving from DIR at the root path (anything not matching /api/, /_/, or custom routes). Only available when the app uses the default static-files mode (field absent in App(.{...})); rejected as an unknown flag when the mode is comptime-hardcoded (.disabled, .dir, or .embedded). A directory in the static tree containing an empty file named .spa becomes an SPA root: any GET/HEAD miss at or below it serves that directory’s index.html (200) so client-routed apps survive deep links and hard refreshes — resolved live against the filesystem on every miss (add/remove a marker with no restart needed); startup only fails fast if a marker has no index.html. Real files and /api/admin paths always win. See Framework → Static files. --background detaches into its own process group and exits 0 only once the server answers its own /api/health; --ephemeral starts a throwaway server on a fresh temp data dir and a free port, printing one JSON line when ready; --ignore-lock starts an untracked instance (no session lock, invisible to serve status/stop/logs). A second serve on the same data dir is refused unless --ignore-lock is passed. See Running the server for the full session/control-verb contract.
• serve stop | status | logs — manage a background serve session via its serve.lock/serve.json session files. status --json/logs --follow for scripting. See Running the server → Control verbs.
• doctor — run the nine frozen preflight checks over this deployment’s config, data dir, and schema; --production escalates the checks that matter more in a real deployment; --json emits NDJSON findings plus a summary object. Exits 0 fully clean, 1 on any error, 2 on warnings only. See Running the server → zigbase doctor.
• migrate — run schema migrations against the data directory and exit.
• superuser create — create a superuser (required before managing collections).
• help — print usage.

zigbase init

Scaffold a starting-point project. Never overwrites: existing files are reported as skipped and left alone, and there is no --force.

In framework mode, run zig fetch --save git+https://github.com/valthon/zigbase afterwards — that is what writes the dependency URL and its content hash into build.zig.zon.

zigbase agents-md

Write AGENTS.md + CLAUDE.md for a project that already exists.

Build flag: -Ddev-tools

init, agents-md, typegen, capabilities, routes, migrate preview, tune and diagnostics are development-time CLI tools: scaffolding, code generation, discovery, measurement comparison and structured doctor checks. They are gated behind -Ddev-tools, on by default. Every artifact we publish — the GitHub release tarballs, the Docker image, and the @zigbase/server npm packages — builds at this default and ships these tools. -Ddev-tools=false is an opt-out offered to a consumer compiling their own binary for their own deployment: it drops these tools and their implementation code from the build. Ordinary doctor and database migration actions remain available. A stripped binary recognizes the gated command names, but exits non-zero with a message pointing back at -Ddev-tools=true instead of running them.

Environment variables

Database backend (experimental)

ZigBase defaults to its embedded SQLite database (<data-dir>/data.db) — the single-binary story, and the only backend in a stock build. A pure-Zig PostgreSQL backend is available behind the opt-in -Dpostgres build flag; it is off by default and adds no libpq, C, or OpenSSL (TLS and SCRAM-SHA-256 use Zig std only), so the default binary stays fully static and OpenSSL-free, with its SQLite data path unchanged.

When compiled in (zig build -Dpostgres=true), setting ZIGBASE_DB_URL to a postgres://user:pass@host:port/dbname?sslmode=require URL selects PostgreSQL at startup; any other value (or an unset var) keeps SQLite. The backend is chosen once, by connection string — “switch via configuration alone”. A stock (-Dpostgres=false) binary handed a postgres:// ZIGBASE_DB_URL does not silently write to local SQLite — it logs a prominent warning and falls back to SQLite, so a misconfigured deployment is visible rather than misdirecting data.

This is a fully supported deployment target with full feature parity: record CRUD, the typed filter/sort/expand/search query engine, the access-rule + abilities + tenancy authorization stack, analytics rollups, the KV/TTL/rate-limit/feature-flag stores, field encryption + key rotation, the deterministic test-clock, and typed-client codegen all work identically on Postgres — verified against a live server in CI. Transport is verified by default since 0.10.0 — an unqualified URL gets sslmode=verify-full (chain + hostname verification, sslrootcert= for private CAs), a server that refuses TLS fails at startup with the exact opt-down instruction, and any explicit mode below verify-full logs a startup warning. See PostgreSQL backend for the full guide.

S3 storage backend (experimental)

ZigBase defaults to local-disk file storage (<data-dir>/storage). An opt-in S3-compatible object storage backend (AWS S3, MinIO, Cloudflare R2, and similar) is available behind the -Ds3 build flag — off by default, alongside -Dpostgres and -Dvector in the same “compiled in only when asked for” family of opt-in build flags.

When compiled in (zig build -Ds3=true), setting ZIGBASE_S3_BUCKET (plus credentials — see the env table above) selects S3 storage at startup instead of local disk; leaving it unset keeps local disk. The backend is chosen once, by configuration — the same “switch via configuration alone” contract as ZIGBASE_DB_URL. A stock (-Ds3=false) binary handed ZIGBASE_S3_BUCKET does not silently keep writing to local disk unnoticed — it logs a loud warning and falls back to local storage.

Downloads are never proxied straight from S3: the server spools an object to a local cache file on first read (ZIGBASE_S3_CACHE_DIR) and serves every subsequent read from that file, so Range requests, conditional requests, ETag, and per-collection cacheability behave identically to local storage. Startup runs a fail-fast HeadObject probe so a bad config is caught at boot, not on first upload. See Known limitations for the write-lock, best-effort-delete, proxy-only-serving, and buffered-multipart caveats.

Email delivery

Three backends, selected by config with a fixed precedence (no code change to switch):

1. ZIGBASE_SENDMAIL_COMMAND set → the message (the same RFC822 bytes the SMTP backend sends) is piped to a local command’s stdin and exit 0 means delivered. This is the standard “delegate delivery to a local MTA/relay, hold no SMTP credentials in the app” setup — point it at sendmail -t -i or msmtp -t. The string is whitespace-split into argv; From: still comes from ZIGBASE_SMTP_FROM. Takes precedence over SMTP.
2. ZIGBASE_SMTP_HOST set → verification and password-reset tokens are emailed over the configured SMTP transport (STARTTLS / implicit TLS / plaintext). TLS verifies certificates by default; ZIGBASE_SMTP_INSECURE disables verification for self-signed relays.
3. Neither set (the default) → tokens are logged to the server (a dev/CI convenience).

Configure a real backend (sendmail command or SMTP) for production.

Rate limiting

Sensitive auth endpoints (login, verification, password-reset) are rate limited — see API → Rate limiting. X-Forwarded-For / X-Real-IP are ignored by default (they are spoofable on direct exposure); the limiter keys on the submitted identity/email. Set --trust-proxy / ZIGBASE_TRUST_PROXY=true only behind a trusted reverse proxy to key on the proxy-supplied client IP; see Known limitations.

Security

ZigBase is secure by default. The bind is loopback (127.0.0.1); expose all interfaces deliberately with --http-host 0.0.0.0 (front it with a firewall / reverse proxy). The JWT secret is per-deployment: leaving ZIGBASE_JWT_SECRET unset generates a strong random secret and persists it at <data-dir>/.jwt_secret (mode 0600), reused on later runs; a provided secret must be ≥32 bytes or the server refuses to start. Auth cookies are Secure by default, so plain-HTTP local dev needs --insecure-cookies (or ZIGBASE_COOKIE_SECURE=false) or the admin-UI login cookie is not stored. An empty ZIGBASE_REALTIME_ORIGINS denies cross-origin browser WebSocket upgrades; same-origin upgrades (the embedded admin UI, or a frontend served from the same binary) are always allowed, so only a separate-origin frontend needs --realtime-origins.

See also

For bounded query diagnostics, build with -Dquery-workbench=true and optionally set .query_workbench = .{ .max_entries = 64, .slow_ms = 100 }. The operator-only SQLite/PostgreSQL workbench reports route-template/structural-shape metrics without SQL or parameter capture, and plans schema-validated SELECT shapes without executing them on SQLite. PostgreSQL reports client-side protocol-exchange durations including network/server wait and result buffering; PostgreSQL plans still return 501. Buffered rows add no per-row clocks or telemetry copies. Telemetry bounds do not limit the backend’s existing result buffering. It is fully absent by default. Completed-statement lifecycle timing separates measured prepare/step/cleanup calls from time held between them, including application pauses and row handling. In-scope prepares fingerprint compiled SQL once and reuse the key on reset; statements prepared outside scope retain execution-time fingerprinting. Each in-scope finalization adds one mutex-guarded store update with a bounded entry scan. This helps distinguish slow SQLite calls from long-lived statements without claiming CPU or full-request latency; enabled counters remain explicitly bounded. HTTP scopes also classify returned status codes and escaping handler errors. Fixed reader/writer buckets measure pool mutex acquisition, excluding connection creation and time holding a connection. Declared durable/scheduled jobs have separate attempt aggregates; queue residence, retry backoff, memory jobs, and app.submit are excluded. See the framework workbench scope.

For request backpressure, compile .admission = .{ .max_requests = 3 } into your app. Excess synchronous HTTP callbacks receive 503 with Retry-After: 1, not an additional waiting queue. Superusers can inspect /api/admission/stats for active, high-water and rejected counts; this endpoint obeys the same limit. Omission compiles out the checks and counters. This does not bound transport-buffered bodies, long-lived realtime sessions, background jobs, or total RSS.

To coordinate HTTP with outstanding memory jobs and app.submit, additionally build with -Dcoordinated-admission=true and set .admission.max_work = 16 alongside .max_requests. Embedded builds forward .@"coordinated-admission" = true to the ZigBase dependency. Queued/running jobs retain one permit through retries; saturation immediately returns error.QueueFull for jobs or the HTTP overload response. Jobs can consume all capacity, so allow room for handlers that enqueue work and handle rejection. Shared diagnostics expose work_limit, jobs, work_high_water, and jobs_rejected; resources reports the compiled ceiling. This optional integration compiles out without its build flag. It counts work, not bytes, and excludes durable jobs, transport buffers and long-lived realtime.

The same build gate also offers an independent retained-copy byte ceiling: .admission = .{ .max_job_bytes = 64 * 1024 }. No max_requests is required: HTTP counting and admission checks compile out, but diagnostics remain available with limit: null and zero HTTP counters. It charges memory-job payload and app.submit name copies before allocation, across queued/running tasks and retries; full capacity returns error.QueueFull. It does not count inline borrowed payloads, pre-enqueue serialization, handler allocations, task headers or allocator overhead, so it is not an RSS cap. Diagnostics expose job_bytes_limit, job_bytes, job_bytes_high_water and job_bytes_rejected; the offline envelope exposes coordinated_admission_max_job_bytes. Omission leaves byte counters untouched. For Zig embedders, App.admission_config.?.max_requests and the admission snapshot’s limit are now ?u32: handle null as no HTTP cap, or unwrap only when your configuration guarantees one. Omit .max_requests rather than setting it to zero to retain a byte-only budget.

Bound long-lived realtime sessions separately with comptime .realtime = .{ .max_connections = 256 }. WS and SSE share the positive cap; the default remains 10,000 and excess upgrades receive 503. Inspect the effective cap and reserved slots through superuser /api/realtime/stats. The Golfsim example demonstrates a smaller cap; larger deployments can explicitly raise it.

zigbase tune --input measurements.json compares observed throughput, p95 latency, and peak RSS against explicit budgets. Pair it with comptime resource profiles; the offline advisor never changes production settings. The framework guide includes a real local measurement workflow and explains its limits. This command requires -Ddev-tools=true (the default); custom builds with development tools disabled omit it.

• Quick start — install and serve.
• API — the REST + WebSocket reference.
• Known limitations — caveats around email, rate limiting, and more.