Self-hosting with heapdb-server

Without a server, HeapDB runs in-process. You install heapdb-core, and the engine lives inside your Python program, with JSONL snapshots for persistence.

heapdb-server runs the same engine as a network service:

• One process hosts many databases. Each one gets a write-ahead log and periodic snapshots.
• It serves the same HTTP Data API as HeapDB Cloud, so heapdb.connect(...) (heapdb 0.6.0 and later) works against your own host (the TypeScript client will too, once it is published to npm).
• An Admin API creates databases and keys, and it enforces quotas and reports usage.
• It runs as a single node on local disk, or as a cluster behind a load balancer on S3 and DynamoDB.
• It writes structured JSON logs and serves Prometheus metrics on a private internal port.

Run it

Build the binary from a heapdb-core checkout. You need a Rust toolchain.

cargo build --release -p heapdb-server
export HEAPDB_ADMIN_TOKEN=$(openssl rand -hex 32)
./target/release/heapdb-server --data-dir ./data   # Data + Admin API on :8080, internal on :9090

Or run the edge image that CI builds from main for linux/amd64 and linux/arm64:

docker run -d -p 8080:8080 -v heapdb-data:/data -e HEAPDB_ADMIN_TOKEN=change-me \
  ghcr.io/heapdb/heapdb-server:edge

Then create a database and an API key with the Admin API, and connect with heapdb+http://<api_key>@localhost:8080/<database_id>. If you put TLS in front, use heapdb:// instead. Keep port 9090 private.

The full API reference, architecture, quotas and configuration are in the server docs. Watch the repository or the roadmap for the first tagged release.