# ZigBase

> Build beyond your team size. ZigBase is an extensible Zig backend with integrated application services, explicit resource controls, and single-binary deployment. Build directly or with coding agents; no AI service is required.

Version 0.13.0. Linux and macOS; Windows is served by the Docker image.

Access rules default to locked, and local plain-HTTP development needs --insecure-cookies. Start with the coding-agent orientation below.

## Start here

- [ZigBase for coding agents](https://valthon.github.io/zigbase/docs/agents/): The compact orientation and highest-cost traps.
- [Machine-readable docs index](https://valthon.github.io/zigbase/docs-index.json): Every published guide with raw-source URLs.

## Getting started

- [Why ZigBase](https://valthon.github.io/zigbase/docs/why-zigbase/): Application leverage and systems control for small teams: why Zig, two development workflows, and the evidence behind the ambition.
- [Overview](https://valthon.github.io/zigbase/docs/overview/): An extensible Zig backend for ambitious applications, small teams, and development with or without coding agents.
- [Quick start](https://valthon.github.io/zigbase/docs/quick-start/): Install ZigBase, create a superuser, start the server, hit the health endpoint, and open the admin UI.
- [Tutorial](https://valthon.github.io/zigbase/docs/tutorial/): Build a backend end to end through the embedded admin UI or the terminal: collections, rules, auth, files, OAuth2, a route, and a cron job.
- [For coding agents](https://valthon.github.io/zigbase/docs/agents/): The ~2k-token entry point for AI agents working with ZigBase — what it is, the traps that bite, the response shapes you can rely on, and which guide to load next.
- [Designing an app](https://valthon.github.io/zigbase/docs/app-genesis/): Turn a product idea into a rules-first ZigBase design: trust boundaries, schema shape, relations, hooks and routes, cursor pagination, realtime, and test placement.

## Guides

- [Recipes](https://valthon.github.io/zigbase/docs/recipes/): Copy-pasteable recipes — provisioning a schema, signup, owner-scoped access rules, validation hooks, custom routes, and DB access in cron jobs.
- [Framework](https://valthon.github.io/zigbase/docs/framework/): Embed ZigBase as a Zig library — comptime record hooks, custom routes, scheduled jobs, a comptime schema with additive auto-migration, pluggable storage/mailer backends, and footprint levers.
- [Testing](https://valthon.github.io/zigbase/docs/testing/): Test a ZigBase app in-process with zigbase.testing — the build wiring, a worked test, the auth seams, and what an in-process test structurally cannot cover.
- [Configuration](https://valthon.github.io/zigbase/docs/configuration/): The full environment-variable reference, CLI commands, and configuration precedence rules for the ZigBase server.
- [TypeScript SDK](https://valthon.github.io/zigbase/docs/typescript-sdk/): The official @zigbase/client TypeScript SDK — auth, records, offset + cursor pagination, files, realtime, and the live store.
- [Docker](https://valthon.github.io/zigbase/docs/docker/): The official ghcr.io/valthon/zigbase image — quick start, data-volume ownership, non-root user, network bind, healthchecks, and tags.
- [Zigapagos + ZigBase full stack](https://valthon.github.io/zigbase/docs/zigapagos-pairing/): Pair a ZigBase framework backend with a same-origin Zigapagos frontend, with explicit ownership, dev, test, OpenAPI, public-signup, and deployment contracts.
- [Dart SDK](https://valthon.github.io/zigbase/docs/dart-sdk/): The official zigbase_client Dart SDK — auth, records, offset + cursor pagination, files, and realtime, for the Dart VM, Flutter, and Flutter web.
- [Python SDK](https://valthon.github.io/zigbase/docs/python-sdk/): The official zigbase Python SDK — sync and async clients for auth, records, offset + cursor pagination, files, realtime, and a generated typed tier.
- [Kotlin SDK](https://valthon.github.io/zigbase/docs/kotlin-sdk/): The official zigbase Kotlin client — a coroutine-first ZigbaseClient over Ktor for auth, records, offset + cursor pagination, and files. Realtime and a typed tier follow.
- [Running the server](https://valthon.github.io/zigbase/docs/serve/): Foreground and background serve sessions, the stop/status/logs control verbs, ephemeral instances, and the doctor preflight.
- [Migrate an existing backend to ZigBase](https://valthon.github.io/zigbase/docs/migration-tools/): Re-platform an existing Rails, Express, PocketBase, or other backend onto ZigBase with schema transplant, data and password import, and parity replay.
- [Deployment](https://valthon.github.io/zigbase/docs/deployment/): Run ZigBase in production with systemd, Docker Compose, Fly, or Railway — TLS, durable state, backups, upgrades, rollback, and the doctor ship gate.
- [Migrate PocketBase to ZigBase](https://valthon.github.io/zigbase/docs/migrate-pocketbase/): Migrate a stopped PocketBase 0.39.11 application with durable decisions, preserved users and timestamps, verified files, parity replay, and rollback evidence.
- [Migrate Express to ZigBase](https://valthon.github.io/zigbase/docs/migrate-express/): Re-platform a Node.js Express service through route, middleware, data, auth, and side-effect discovery; deterministic import; parity replay; and rehearsed cutover.
- [Migrate Laravel to ZigBase](https://valthon.github.io/zigbase/docs/migrate-laravel/): Re-platform a Laravel backend through route, middleware, Eloquent, policy, auth, queue, and file discovery; deterministic import; parity; and cutover rehearsal.
- [Migrate a Go service to ZigBase](https://valthon.github.io/zigbase/docs/migrate-go/): Re-platform a Go web service through router, middleware, data, transaction, auth, worker, and wire discovery; deterministic import; parity; and cutover rehearsal.
- [Migrate a Rails API to ZigBase](https://valthon.github.io/zigbase/docs/migrate-rails-api/): Re-platform a Rails API-only backend through observed route, Active Record, authorization, job, and storage discovery; deterministic import; parity; and cutover rehearsal.
- [Migrate a complete Rails application](https://valthon.github.io/zigbase/docs/migrate-rails-fullstack/): Coordinate Rails backend and Zigapagos presentation migration through versioned handoffs, a reconciled route map, backend and browser parity, and rehearsed cutover.
- [Engineering backlog](https://valthon.github.io/zigbase/docs/roadmap/): Priorities, implemented foundations, and acceptance criteria for resource efficiency, developer leverage, and measured growth.

## Feature guides

- [PostgreSQL backend](https://valthon.github.io/zigbase/docs/postgres/): Run ZigBase on PostgreSQL — the -Dpostgres build, ZIGBASE_DB_URL, multi-instance realtime, migrating from SQLite with migrate-db, and pgvector.
- [Multi-tenancy](https://valthon.github.io/zigbase/docs/tenancy/): Account-scoped collections — enabling tenancy, tenant_field, accounts/memberships/invitations, roles, and the @request.account rule macros.
- [Relationship abilities](https://valthon.github.io/zigbase/docs/abilities/): Per-collection, per-action authorization by the principal's relationship to the row — declaring abilities, ctx.can, and the abilities endpoint.
- [Full-text & vector search](https://valthon.github.io/zigbase/docs/search/): Ranked ?search= queries on searchable fields, operators, how search composes with filters and rules, and opt-in -Dvector KNN.
- [Product analytics](https://valthon.github.io/zigbase/docs/analytics/): Capturing immutable events with ctx.track, declarative rollups, and the tenant-scoped analytics read API.
- [Email](https://valthon.github.io/zigbase/docs/email/): Sending application mail — templates, SES/Postmark/SMTP providers, verified senders, bounce suppression, and asserting mail in tests.
- [Jobs & webhooks](https://valthon.github.io/zigbase/docs/jobs-and-webhooks/): Background queues, workers, and job kinds — plus signed outbound webhooks with retry, backoff, and idempotency keys.
- [Realtime broadcast](https://valthon.github.io/zigbase/docs/realtime-broadcast/): Pushing to custom WebSocket channels from routes and jobs — signal vs broadcast, and gating subscriptions with canSubscribe.
- [Two-factor authentication](https://valthon.github.io/zigbase/docs/two-factor-design/): Compile-time factor selection, user and group requirements, TOTP and WebAuthn enrollment, recovery, and shared session enforcement.
- [Resumable uploads](https://valthon.github.io/zigbase/docs/resumable-uploads/): Bounded, opt-in client file transfers with current commit authorization. Default process-local RAM or SQLite/local restart persistence; neither mode is streaming or cross-instance recovery.
- [Image thumbnails](https://valthon.github.io/zigbase/docs/thumbnails/): Named PNG, JPEG and WebP derivatives using opt-in ImageMagick with deployment resource controls.

## Reference

- [API](https://valthon.github.io/zigbase/docs/api/): The ZigBase HTTP REST and realtime WebSocket reference — collections, records, query grammar, access rules, auth, OAuth2, files, and realtime.
- [Fields](https://valthon.github.io/zigbase/docs/fields/): The complete catalog of ZigBase field types and their options — text, email, url, editor, date, autodate, bool, number, json, select, relation, and file.
- [Known limitations](https://valthon.github.io/zigbase/docs/known-limitations/): Current caveats in ZigBase — auth/email, framework hooks, schema migrations, fields, the scheduler, platform/UI gaps, and deferred work.
- [Changelog](https://valthon.github.io/zigbase/docs/changelog/): Release history for ZigBase, following Keep a Changelog and Semantic Versioning.
- [Observability & machine-readable output](https://valthon.github.io/zigbase/docs/observability/): Structured logging, the frozen error-code registry, JSON CLI output, and capability discovery — the contracts tools and agents build on.
- [Agent evaluations](https://valthon.github.io/zigbase/docs/agent-evals/): Run ZigBase's provider-neutral Genesis evaluation, understand deterministic grades, and preserve three-run release evidence without committing transcripts.
- [OpenAPI export](https://valthon.github.io/zigbase/docs/openapi/): Export deterministic OpenAPI 3.1.2 JSON for live collection CRUD and framework-declared consumer routes, with honest access and redacted secret metadata.

## Optional

- [Source repository](https://github.com/valthon/zigbase): Issues, releases, examples, and canonical Markdown.