HeapDB Cloud

HeapDB Cloud runs HeapDB for you. You sign in, create a database, and get a connection URL. The same Python API you use locally then talk to a hosted database instead of an in-process engine, so there is no server to run, no snapshots to manage and nothing to back up yourself.

What you get

• Databases: each one is an isolated heap with its own effects, kernels, events and learned links.
• A connection URL per database that every client accepts.
• API keys with scopes, shown once, revocable at any time.
• Connectors per database: Sentry, PostHog, HTTPS ingest, Kafka and OpenTelemetry, run by HeapDB. See Connectors.
• Usage (API requests, storage) in the console, updated every 15 minutes.
• Plans: Free (no card), Pro at $5 / month plus usage, and Team (contact us).

Connection URL

heapdb://<api_key>@api.heapdb.com/<database_id>

The URL contains a secret. Treat it like a database password: keep it in an environment variable (by convention HEAPDB_URL) or a secret manager, never in source control or client-side code.

Quickstart

1. Sign in and create a database

Go to the console, sign in with GitHub, and choose Create database. Pick a name (lowercase letters, digits and hyphens) and the region. Provisioning takes a few seconds.

2. Copy the connection URL

The database page shows the full connection URL once, right after the database (or a new key) is created. Copy it then. Afterwards only the key prefix is shown; if you lose a key, create a new one and revoke the old one.

export HEAPDB_URL="heapdb://hdb_live_…@api.heapdb.com/db_…"

3. Connect

Python. The calls are the heapdb-core API. heapdb.connect is the remote client, and it ships in heapdb 0.6.0 and later (pip install 'heapdb>=0.6'):

import os
import time
import heapdb
 
db = heapdb.connect(os.environ["HEAPDB_URL"])
db.register_effect("error_spike", kernel=heapdb.ExponentialDecay(half_life=3600))
now = time.time()
db.insert(entity="checkout", time=now - 600, type="deploy", features={"pr:1234"})
res = db.top_causes(entity="checkout", effect="error_spike", at=now, k=3, explain=True)
for c in res:
    print(c.rank, c.event.short(), round(c.score, 3))

TypeScript (coming: @heapdb/client is on heapdb-core main and not yet published to npm):

import { connect } from "@heapdb/client";
 
const db = connect(process.env.HEAPDB_URL!);

MCP: the HeapDB memory MCP server (available on request) reads the same URL from HEAPDB_URL, so an agent's memory can live in a hosted database:

{
  "mcpServers": {
    "heapdb": {
      "command": "<command from your access invite>",
      "env": { "HEAPDB_URL": "heapdb://hdb_live_…@api.heapdb.com/db_…" }
    }
  }
}

Connectors

Each database has a Connectors tab. Connect Sentry or PostHog, consume a Kafka topic, point an OpenTelemetry Collector at an OTLP endpoint, or POST JSON from anything to a private ingest URL. HeapDB runs the connector, maps each record to a HeapDB event (the console previews the mapping on a sample record), writes it through the Data API, and shows the connector's health, last sync, events sent and last error.

Ingest URLs live at https://ingest.heapdb.com. Tokens and signing secrets are shown once; credentials you enter are encrypted with AWS KMS and only the connector runner can read them. Connector writes count as API requests of the database. Free includes 1 connector per database, Pro 10. Details, mapping rules and snippets: Connect from HeapDB Cloud.

Plans and limits

Sizes are binary: 1 MB = 2²⁰ bytes, 1 GB = 2³⁰ bytes. The free plan needs no card. Upgrading to Pro opens Stripe Checkout; payment methods, invoices and cancellation are handled in the Stripe customer portal, linked from Billing in the console.

Team is not self-serve: contact us with your expected databases, storage and request volume, and we set it up with you. We'll add dedicated servers for Team and larger plans later. Today every plan runs on the shared, load-balanced data plane.

How Pro is billed

• $5 / month base fee, which includes 1 GB of storage and 1 million API requests per billing period.
• **Storage above 1 GB: $5 per GB-month**, measured as the **average** over the period, not the peak. Holding 3 GB for the whole month is 2 extra GB-months ($10); holding 3 GB for half the month and 1 GB for the other half averages 2 GB, so 1 extra GB-month ($5).
• Requests above 1 million: $0.50 per million, summed over the period.
• The included amounts are never charged: Stripe prices the usage in tiers, and the first tier (up to the included amount) costs $0. A month with 900k requests and 800 MB of storage costs exactly$5.
• Usage is reported to Stripe every 15 minutes with idempotent meter events and appears on the invoice at the end of the period.

How limits apply

• Databases per account is checked when you create one. Delete a database or upgrade to add more.
• Connectors per database is checked the same way when you add one.
• Storage and the per-database rate limit are enforced by the data plane on each request. Over the rate limit, requests get 429 with Retry-After. On Pro, storage beyond the included 1 GB is billed rather than refused, up to a safety cap of 100 GB per database.
• On Free, the data plane counts requests per billing period (calendar months). At 100k, requests get 429 monthly_quota_exceeded with Retry-After set to the end of the period; the database's info endpoint keeps answering. On Pro, requests are not capped: above 1M they are billed.
• If a payment fails, you get a grace period (7 days by default) to update the card. After that, databases are suspended: data is kept but requests are refused until the invoice is paid. Paying restores access automatically.

Data location and backups

How the data plane (heapdb-server) stores data:

• One region at launch: AWS us-west-2 (Oregon).
• Every write is appended to the database's write-ahead log in encrypted object storage (S3) and acknowledged only once it is durable; snapshots are written every few minutes.
• Backups are object versions kept 7 days on Free and 30 days on Pro and Team.
• Deleting a database deletes its live data immediately; backups expire on their normal schedule.
• Point-in-time restore and branching are not part of v1.

Security model

Both sides below are implemented: the console and the open-source data plane, heapdb-server.

• Sign-in is GitHub OAuth (authorization code with PKCE). We read your profile and primary email only.
• Sessions are httpOnly, SameSite=Lax, Secure cookies, encrypted and backed by a server-side session that sign-out revokes immediately. Every change in the console is protected against cross-site requests (origin check plus a per-session token).
• API keys are 256-bit random secrets. The console shows a key once; we store only its SHA-256 hash and a short prefix for display. The data plane receives the hash, never the key.
• Scopes limit what a key can do: read (queries and reports), write (insert events, feedback) and admin (register effects and rules, forget entities). Give each service the smallest set it needs, and an expiry where you can.
• Revocation takes effect immediately on the data plane.
• Isolation: each database is a separate engine instance and directory; keys are bound to one database.
• Control plane ↔ data plane traffic uses a separate admin credential that is never exposed to clients, over TLS, from an allow-listed address only.
• Connector credentials are encrypted with per-value data keys from AWS KMS before they are stored. The website may encrypt with that key but not decrypt; only the connector runner can. Ingest tokens are stored as SHA-256 hashes.
• Key, database, connector and billing changes are written to an audit log.

What's next

The hosted data plane is heapdb-server. It's the Rust engine behind the same API as the local library, clustered behind a load balancer. You can also run heapdb-server on your own machines: it's on heapdb-core main (0.6.0), with an edge container image built from main. See Self-hosting for how to run it, or use heapdb-core in-process. The same calls work against a connection URL.