Local quickstart

The local platform runs the exact same DBLab engine the cloud platforms run, as containers on your machine: no cloud account, no tunnels, branches on 127.0.0.1. It is the fastest way to try tendb, and a real dev target — same CLI, same console, same snapshot semantics.

Prerequisites

• A ZFS-capable Docker host. This is the one honest requirement, and Docker Desktop on macOS cannot provide it — its LinuxKit kernel has no ZFS module. The preflight script solves it:
  • macOS: creates a colima VM (vz + Rosetta — the DBLab images are amd64 and run emulated), installs zfsutils-linux inside it, and builds a file-backed zpool. Homebrew required; colima is installed for you if missing.
  • Linux: same steps natively (needs sudo; ZFS must be available for your kernel, which stock Ubuntu provides).
• Terraform >= 1.11 and Node.js >= 20 for the CLI. Install the CLI globally (npm install -g @10play/tendb) so the bare tendb commands below work — or prefix every command with npx @10play/tendb.
• A source Postgres URL — or nothing: the scaffold provisions a seeded demo source container (500 users, 5000 orders) when you don’t bring one.

Zero to first branch

1. Scaffold it.

   From any project directory:

   tendb init --platform local

   Accept the defaults (or pass --yes — the local platform needs no answers) and you get a tendb/ directory — the Terraform for the engine + tendb-snapshotd containers, a seeded demo source, the preflight script — plus a tendb.json pointing the CLI at it.

2. Bring it up.

   tendb up

   up first runs the preflight (tendb/scripts/host-setup.sh — idempotent; on macOS it installs/starts the colima VM and builds the zpool, and up points terraform at the colima Docker socket for you), then applies the stack: engine container (API on 127.0.0.1:2345), snapshotd, the demo source (unless you set source_url in tendb/terraform.tfvars), and the discovery file the CLI reads (~/.tendb/local/params.json).

   Note

   The verification token lands in local Terraform state — a documented local-only concession (the cloud platforms use write-only secret arguments). It is your dev machine; keep the deploy dir private.

   Under the hood / doing it by hand

   The same flow by hand is bash tendb/scripts/host-setup.sh, export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock, then terraform -chdir=tendb init && terraform -chdir=tendb apply — or use packages/tendb/terraform/examples/local from a repo clone. Setting TENDB_PLATFORM=local env-only (no tendb.json) works too.

3. Branch, connect, snapshot.

   tendb status shows transport local and the sync progress — the demo source syncs in about a minute. Then:

   tendb branches create my-feature
   tendb psql my-feature -- -c 'select count(*) from users'
   tendb snapshots create        # ~10s round-trip through snapshotd

   Clone ports (6000+) are published on loopback and forwarded to your Mac by colima, so the printed URI dials as-is. The DBLab embedded UI is on http://127.0.0.1:2346 (tendb ui opens it), and tendb console serves the full dashboard — here is its SQL editor on a branch:

   

   The console's SQL editor, querying a branch of the seeded demo data.

Differences from the cloud platforms

• No tunnels — everything is already on 127.0.0.1; tendb tunnel -p still works via a small TCP relay.
• amd64 under Rosetta on Apple Silicon: noticeably slower than native, entirely fine for dev-sized databases.
• Sizing is the VM’s problem: the size variable still sets port-pool width and per-clone Postgres settings, but CPU/RAM/disk come from the colima VM (TENDB_VM_CPUS, TENDB_VM_MEMORY, TENDB_POOL_SIZE env vars for the preflight).

Next steps

Example appapps/example in the repo: a scaffolded local platform + a demo that branches, migrates, and queries.

PlatformsHow local, AWS, GCP, and Azure share one engine contract.

AWS quickstartThe production path: scaffold, apply, and branch in your own AWS account.