kynetradb documentation

One Rust binary. Append-only log. Four query shapes (KV, document, BM25, vector). Auth, files, realtime, agents, and an LLM runtime included. Deploys anywhere a container or VM runs.

Private preview · reference catalogue · db.kynetra.dev

Introduction

kynetradb is a data engine designed to collapse the typical "modern" search stack into a single process. Instead of Algolia for search, Pinecone for vectors, Redis for cache, and Postgres for analytics — each fed by its own CDC pipeline — you run one binary that accepts JSON writes and answers all four query shapes against the same on-disk log.

The architecture is intentionally boring: an append-only write-ahead log feeds a set of in-memory indexes ("personalities"). Restart replays the log. Replication ships the log. Backup is the log. There is no separate index that can drift from the source of truth.

When this is the right tool

  • You need search + vector + KV + document over the same dataset.
  • You want one binary you can self-host, not four SaaS bills.
  • Your working set fits in RAM on a single node (typically <100M entities).
  • You're comfortable with last-writer-wins semantics and no SQL.

When it isn't

  • You need interactive multi-statement transactions over HTTP. The engine reads from pinned snapshots and POST /v1/transactions commits several writes atomically when stated conditions hold; see conditional and optimistic transactions for what it covers.
  • Your dataset is hundreds of millions of rows and grows unboundedly.
  • You need Postgres-wire-compatible query access (use the Postgres sink instead).

Reference pages

These pages go deeper than this overview. The capability catalogue and the migration page are generated from checked-in data, so the counts on them always match the entries.

  • Capability catalogue: 125 capabilities, each with its state, where it is reached, its limits and its evidence.
  • Migration: which sources can be moved in, what each one leaves behind, and which are not supported.
  • Architecture: the log, the engine, projections, storage backends and replication.
  • Security: identity, access, keys, audit, erasure and tenancy, with the limits stated.
  • FAQ: answers to common questions, each tied to what the engine does.
  • Use cases: patterns built from capabilities that exist today.

Quickstart

Run locally

KynetraDB distribution is scoped during private preview.
Request a preview for the approved local or hosted evaluation path.

First user (becomes Admin automatically)

curl -X POST http://localhost:8080/v1/auth/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"strong-pw","display_name":"You"}'

Login & write a row

TOKEN=$(curl -s -X POST http://localhost:8080/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"strong-pw"}' | jq -r .token)

curl -X POST http://localhost:8080/v1/entities \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"product","attrs":{"title":"Aurora Espresso","price":2200}}'

Search

curl -X POST http://localhost:8080/v1/search \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"q":"espresso","top_k":10,"kind":"product"}'

That's a complete write → search loop in four HTTP calls. Openhttp://localhost:8080/admin for the embedded admin UI.

Core concepts

The universal log

Every write — entity put, collection record, user signup, file upload metadata, agent run — is appended to a single on-disk log as a typed event. The log is the source of truth. Indexes are derived state and can be rebuilt by replay.

The log is a directory of segment files. Records are length-prefixed msgpack payloads in CRC-32-checked frames, and the current segment format is version 4. Whether each write is synced to disk is configurable (KYNETRA_SYNC), trading durability against write throughput.

Entities

An entity is the atomic unit of writeable data:

{
  "id": "01K3X...",          // ULID, auto-assigned if omitted
  "kind": "product",          // free-form tag — your "table name"
  "attrs": { ... any JSON ... }
}

kind is a free-form string. attrs is arbitrary JSON. Entities are schema-free at this layer — use Collections (below) when you want field validation.

Personalities

A personality is an in-memory index built from the log. Four ship by default:

  • KV — exact lookup by id.
  • Document — JSON predicate filtering over attrs.
  • Search — BM25 full-text over indexed text fields.
  • Vector — exact cosine search over the embedding stored on an entity. The HNSW and SPANN indexes are implemented in the engine but are not yet enabled by the server.

All four read the same entity state. There is no separate write path per personality and no CDC between them.

Collections

A Collection is a typed schema layered over entities. Fields, validation, uniqueness, and per-role CRUD rules are enforced server-side. Records live in the same log as raw entities.

Last-writer-wins

Same-id writes overwrite. There is no row-level locking and no interactive multi-statement transaction over HTTP. The engine reads from pinned snapshots, and POST /v1/transactions commits several writes atomically when stated conditions hold; see conditional and optimistic transactions. If you need interactive transactions across multiple entities, this isn't the right engine.

Auth & roles

Passwords are hashed with bcrypt (cost 12). Access tokens are stateless JWTs signed with HS256. They last one hour by default and refresh tokens thirty days; both lifetimes are settings (KYNETRA_ACCESS_TTL_SECS, KYNETRA_REFRESH_TTL_SECS). The signing secret is generated on first run and persisted to the universal log so tokens survive restarts.

Roles

  • Admin — full access. First signup is auto-Admin.
  • Editor — write to entities and collections (per rule).
  • Viewer — read-only.

Sending the JWT

Authorization: Bearer <token>

Every /v1/* route except /v1/auth/signup and/v1/auth/login requires a valid token.

Entities

The lowest-level write API. Use it directly when you don't need a typed schema.

MethodPathPurpose
POST/v1/entitiesCreate or update (upsert by id)
GET/v1/entities/:idFetch by id
DELETE/v1/entities/:idTombstone (soft delete)
POST/v1/filterJSON predicate filtering

See API reference → Entities for exact payloads.

Vector search

Store an embedding in the entity's embedding field (an array of floats). Query with POST /v1/vector using a query vector and top_k.

POST /v1/vector
{
  "vector": [0.012, -0.34, ...],
  "top_k": 10,
  "kind": "product"
}

The preview server performs exact cosine search: it scores every entity that has an embedding of the query's dimension. The HNSW and SPANN indexes are implemented and benchmarked in the engine but the server does not enable them yet; see vector similarity search. Dimensionality is inferred from the first vector inserted; subsequent writes with a different dim are rejected.

Filters

JSON predicate syntax over attrs:

POST /v1/filter
{
  "kind": "product",
  "where": {
    "and": [
      { "field": "price", "op": "lt", "value": 5000 },
      { "field": "vendor", "op": "eq", "value": "Aurora" }
    ]
  },
  "limit": 50
}

Operators: eq, neq, gt, gte, lt, lte, in, nin, contains, starts_with. Logical: and, or, not.

Collections

PocketBase-style typed schemas. Defines a name, field types, validation, and per-operation role rules.

Field types

text, long_text, number, integer,bool, email, url, date,json, select, relation, file.

Per-field validation

required, unique, min, max, options (for select), regex.

Per-operation rules

Each collection has a rules object mapping list / view / create / update / deleteto an array of role names: ["admin", "editor"] or ["*"] for public.

POST /v1/collections
{
  "name": "posts",
  "fields": [
    { "name": "title", "type": "text", "required": true },
    { "name": "body",  "type": "long_text" }
  ],
  "rules": {
    "list":   ["*"],
    "view":   ["*"],
    "create": ["admin", "editor"],
    "update": ["admin", "editor"],
    "delete": ["admin"]
  },
  "created_at": 0,
  "updated_at": 0
}

File storage

Two backends:

  • Local — files in a configurable data directory.
  • S3 — any S3-compatible endpoint (AWS S3, R2, MinIO, Wasabi, B2, DO Spaces). AWS SigV4 signed in-tree.

Object keys combine a content-hash prefix with a unique id, so identical uploads are stored separately; the SHA-256 is recorded in the file's metadata.

Pick via KYNETRA_FILE_BACKEND=local|s3.

# Multipart upload
curl -X POST http://localhost:8080/v1/files \
  -H "Authorization: Bearer $TOKEN" \
  -F file=@image.png

Realtime

Client applications subscribe through the realtime WebSocket at /realtime/v1, which applies row-level policy per subscriber; see realtime subscriptions. The server-sent-events stream below, like the change feed, is an operator interface rather than a client API, and its events are not filtered per row.

Open GET /v1/realtime with optional topics andkinds query params. The server pushes named events (change) with a JSON payload describing each write.

const es = new EventSource(
  "http://localhost:8080/v1/realtime?topics=entities&kinds=product",
  { headers: { Authorization: `Bearer ${token}` } }
);
es.addEventListener("change", (evt) => {
  const data = JSON.parse(evt.data);
  console.log("write:", data);
});

Backed by a tokio::broadcast channel. Slow consumers see dropped messages signaled via SSE comments rather than blocking the writer.

LLM runtime

A unified completion API in front of Ollama (local), Anthropic Claude, and OpenAI. Configure providers via /admin/providers; the samePOST /v1/llm/complete call works against any of them.

POST /v1/llm/complete
{
  "provider": "anthropic",       // or "openai", "ollama"
  "model": "claude-opus-4-7",
  "messages": [{ "role": "user", "content": "Hello" }],
  "max_tokens": 256
}

Cost (input + output tokens × per-million rate) is tracked per call.

Agents

An agent is a stored LLM tool-use loop. You define a system prompt, pick which of the 18 registered actions it can call (e.g. list_collections, list_records, recall_memory), and a model. Three of the registered actions are approval-gated; see built-in agent actions.

Run it ad-hoc via POST /admin/agents/:id/run or schedule it viaPOST /admin/agents/schedules. Each run is appended to the log with full message history, tool calls, results, and token cost — fully auditable.

Actions can require approval: when an agent attempts a guarded action, the run pauses and an entry appears in /admin/agents/approvals for a human to approve or reject.

DB sinks (outbound mirroring)

Every entity write can be mirrored asynchronously to one or more external databases. The log is the source of truth; sinks are derived consumers.

13 sinks are implemented:

  • BigQuery, DynamoDB, Firestore
  • Cloudflare D1, KV, R2, Vectorize
  • MongoDB Atlas (Data API), Upstash Redis, Pinecone
  • Supabase, a PostgREST-style endpoint, PlanetScale (MySQL-compatible)

Sinks are off unless KYNETRA_ENABLE_SINKS is true, and each target is configured by environment variables when the server starts. /admin/sinks lists the registered sinks and /admin/sinks/ping tests each one. Mirroring is fire-and-forget, with no retry and no backfill; see outbound database sinks.

Cloud providers (control plane)

The server has adapters for fifteen cloud providers: AWS, Google Cloud, Azure, Fly, Railway, Render, Heroku, DigitalOcean, Linode, Vultr, Oracle, QuantumOS, Supabase, Neon and Cloudflare. Twelve can create a container service or a virtual machine from an image you supply; Supabase and Neon create PostgreSQL projects; Cloudflare offers inventory and edge-gateway calls and no deploy. Credentials are stored AES-256-GCM-encrypted in the universal log.

Routes live under /admin/providers/*. These adapters are code that calls provider APIs, not tested installers: one provider has an opt-in live test, and no adapter attaches persistent storage. They are separate from the19 documented deployment target profiles on the deploy page. See cloud provider adapters.

GDPR endpoints

MethodPathPurpose
POST/v1/gdpr/exportAdmin only. Export the data held for one user, named by user_id in the request body, as JSON. Refused above 100,000 entities.
DELETE/v1/gdpr/user/:idHard-erase user and tombstone every entity they wrote

Admin UI

Embedded single-page admin available at /admin/. No build step, no separate process — shipped as a static HTML/JS bundle inside the server binary.

Tabs:

  • Database — Cloudflare D1-style: stat cards, query REPL, time-travel restore.
  • Collections — visual schema editor.
  • Files — browse/upload/delete.
  • Agents — author, run, schedule, approve.
  • Sinks — configure outbound DB mirrors.
  • Providers — multi-cloud deploy.
  • Connect — copy-paste snippets for 12 frameworks.

Deploy

19 deployment target profiles are retained for architecture planning. Target profiles, not one-click deployments.

See the deploy page for the full matrix.

Environment variables

VarDefaultPurpose
KYNETRA_DATA/var/lib/kynetraWAL + index dir
KYNETRA_BIND0.0.0.0:8080Listen address
KYNETRA_FILE_BACKENDlocallocal or s3
KYNETRA_S3_BUCKET—Required if backend is s3
KYNETRA_S3_ENDPOINTAWSSet for R2, MinIO, etc.
KYNETRA_SYNCtrueSync the log on write

KYNETRA_SYNC syncs the log on every write when it is true or 1; any other value turns that off.

SDKs

Official client SDKs at sdks/:

  • TypeScript / JavaScript — @kynetra/sdk (fetch-based, isomorphic).
  • React — @kynetra/react: useEntity, useSearch, useCollection, useRealtime, useFiles.
  • Vue 3 — composables mirroring the React hooks.
  • Svelte — stores for entities, search, realtime.
  • Python — sync + async clients (httpx-based).
  • Go — single-import package using net/http.
  • Rust — typed client using reqwest.

All SDKs share the same wire shape — pick by language, behavior is identical. See examples/06-clients/ for runnable single-file samples.

Operations

Health endpoints

  • GET /healthz — liveness, returns 200 if process is up.
  • GET /readyz — readiness, returns 200 once WAL replay finishes.

Metrics

GET /metrics exposes Prometheus-format request counters and latency per route. It is private by default: it needs the global service key unless public metrics are enabled. Per-route p50/p95/p99 and error rate are read by an administrator at GET /admin/db/slo. See metrics, logs and traces.

Backups

The data directory is the backup. cp -a data/ backup-$(date +%F)/while the server is running is safe (the log is append-only). For a copy taken at one position, and for an incremental chain, see portable backup bundles and the incremental backup chain.

Restore

Drop the backup data directory in place and restart. The admin time-travelUI also exposes point-in-time restore from snapshot ranges viaPOST /admin/db/restore.

Replication

Streaming replication: a replica pulls the primary's log over HTTP and applies it. Replicas are asynchronous unless semi-synchronous quorum commit is switched on (KYNETRA_QUORUM_PEERS), and there is no automatic failover. A Raft prototype exists under simulation and is a research item. See streaming replication, quorum commit and Raft consensus.

Security

  • Bcrypt cost 12 for passwords.
  • JWT HS256: access tokens last one hour and refresh tokens thirty days by default. The signing secret is rotated from the command line on the server host (local only), and promoting the pending secret ends outstanding access tokens; see signing-secret rotation.
  • AES-256-GCM for stored cloud-provider credentials (the provider vault). Sink credentials are read from environment variables.
  • Administrative routes are for operators; restrict network access to them and see Security.
  • Constant-time password comparison.
  • CORS allowlist configurable; no wildcard by default.
  • Audit log: a separate HMAC-chained audit log records administrative actions. It does not cover every action; see audit log.

Security disclosures: security@kynetra.dev.

FAQ

Does it speak Postgres wire protocol?

No. Postgres clients (psql, JDBC, psycopg2, sqlx) won't connect. Use the HTTP API or the SDKs. If you want a Postgres-readable mirror, enable the Postgres sink.

How big can it scale?

Single-node working set is bounded by RAM (indexes are in-memory). Measured: one million entities resident in 7,514 MB of RSS — about 7,874 bytes per entity — loading in 40.6 s and booting from checkpoint in 14.2 s. This is local scope, on one host (Apple M5, 32 GB RAM), at a single measured point. Beyond what one node holds, shard at the application layer or use the outbound sinks to offload.

How is it different from PocketBase / Supabase?

PocketBase is SQLite + custom server; Supabase is Postgres + extensions. kynetradb is a purpose-built engine where search, vector, KV, and document share one log — no extension or extra service per query shape. The trade-off: no SQL.

How is this documentation used?

This is the public reference catalogue for a private-preview product. It describes the API and operating model used to scope a preview for a specific workload.