HexDB

Search HexDB

Find a feature, an API example, a step, a FAQ answer or a term, then jump to it.

Operations

A CLI and an API for Everything the UI Does.

Nothing in HexDB is only reachable by clicking. The hexdb command starts, stops, inspects, backs up and queries a server, and every dashboard action is a documented REST call you can script.

hexdb --help
hexdb start [-s]                 start the server (-s: in the background)
hexdb stop [--force]             stop it gracefully
hexdb health                     is it up?
hexdb status                     status and metrics
hexdb secret                     print a new random key
hexdb backup [--name N] [--list] back up the running server
hexdb sql "SELECT ..." [-p V]   run a SQL query and print a table
hexdb put|get|ls <files> ...    upload, download and list files
hexdb doc insert|get|patch|replace|upsert|update   documents; every write idempotent, retried safely
hexdb tx @transfer.json          run a transaction
hexdb schema show|check|set      schemas and their parent links
hexdb rm <t> --filter ... | <ids> | <folder> -r   preview, confirm, delete
hexdb deletes list|show|restore|purge   the delete history; undo a delete
hexdb trash <t>                  a tessellation's trash
hexdb config get|set|history     the lattice configuration, its versions and rollback
hexdb plugins add|remove|list    manage the plugin registry
hexdb lattice spawn --count 2    start more hexes that join this lattice
hexdb lattice list|stop          list or stop them
observability and backups
curl http://localhost:7700/status                        # documents, memory, disk, vertices, lattice, lag
curl "http://localhost:7700/status/history?minutes=60"   # a sample every 15 s, kept for 6 hours
curl "http://localhost:7700/logs?level=warn&limit=100"   # tail, search and filter the log
curl -X POST http://localhost:7700/backup -d '{"name": "nightly-1"}'   # consistent, while serving writes
curl http://localhost:7700/openapi.json                  # the REST API as OpenAPI 3.1
Backups
Consistent and online. SSTables are hard-linked, the WAL is rotated, and writes keep flowing. Restore by pointing a hex at the copy with the same keys.
Metrics and logs
A sample every 15 seconds, kept for six hours across restarts. The last 5,000 log records are searchable live. Export both with the OpenTelemetry plugin.
Settings and configuration
A hex's limits, retention and session length change live from the UI or API. Lattice-wide settings such as the AI provider are encrypted, versioned and checksummed on every hex, with history and one-step rollback.
Upgrades
Stop, replace the binaries and the UI, start. Older file formats are read and rewritten by compaction. In a lattice, restart one hex at a time, replicas first and the Overseer last; a stopping Overseer hands over or keeps its role, so no write fails.
Packaging
A Windows installer and a macOS installer, archives for every platform, Debian packages from an APT repository, a Docker image and compose file, a systemd unit, and Homebrew and Chocolatey packages.
Health checks
/health is public and cheap. /status adds documents, memory, disk, vertices, lattice membership and replication lag for anything that wants detail.

Admin UI

A Control Room in Every Hex.

Every HexDB server hosts its own admin UI. Watch the lattice, browse and edit documents, run GraphQL, manage indexes, schemas, streams, functions, users and roles, read the audit trail and tail the log, all from one place and all through the same permissions as the API.

Listen to the podcast - 6:02 min

Open Source, Hosted, and the Admin UI

Running the Apache-2.0 code yourself or having HexDB Enterprise run it, who looks after updates and backups, and a tour of the admin UI, from the document browser and query advisor to audits, backups and lattice health.

0:00--:--
http://localhost:7700/ui/
The Dashboard of the four-hex playground lattice: 81,915 documents, the activity chart, vertex health, and the lattice card showing Carl taking writes while Donut and Katia share the slices and Mordecai answers queries. Hover a number to match it with the notes below, or click the image to enlarge it.

What You're Looking At

  1. 1
    Only the Pages Your Role Allows

    The sidebar shows what the signed-in user may use. Everything else is hidden here and refused by the server anyway.

  2. 2
    Live Figures

    Documents in memory and on disk, tessellations, memory and disk against their budgets, writes and reads per minute, uptime and version.

  3. 3
    Activity, 15 Minutes to 6 Hours

    Documents per tessellation, operations per minute, or storage over time. The history survives restarts.

  4. 4
    Vertex Health

    The six memory vertices of this hex, each its own region of RAM, with its size and repairs. Any two can fail and documents are rebuilt from the rest; a failed vertex is rebuilt and reassigned.

  5. 5
    The Lattice

    Every hex with its role, address, replication state and lag. “Add a hex” shows the settings a new server needs to join.

  • Served at /ui/ by every hex, replicas included. No separate service to deploy or secure.
  • It calls the same API as any client, with the signed-in user's permissions, so what you see is what the API allows.
  • Light, dark and system themes. Keyboard shortcuts in the query console (Ctrl+Enter runs).
  • Sessions use HttpOnly, SameSite cookies with CSRF protection; MFA and API keys are managed on the Account page.

Every Page, and What It Does

Dashboard
Live document, memory, disk and operation figures, activity charts, vertex health, the lattice and 'Add a hex'
Queries
A GraphQL and SQL console with completion, examples, history, and JSON or table results
Tessellations
Create and delete; manage indexes (with analyzer choice and suggestions) and schemas, with version history and rollback
Schemas
Every tessellation's schema versions and parent links: edit the next version, apply it now or later, or roll back
Documents
Browse with filters and sorting; create, edit and delete documents, with a preview of what a delete removes and Undo afterwards; filter files by their metadata
Deletes
The delete history: who deleted what, with Restore and Purge
Files
Browse folders, upload by dragging, preview and play media, search metadata and AI tags, share files and folders by link, and manage versions and the trash
Ask
Ask the AI about your data; it looks things up with your permissions
Shares
Your sharing links (everyone's, for administrators): downloads, expiry, and deleting a link
Streams
Create streams, publish, watch messages arrive live, consumer groups, deliveries, and code to subscribe
Queues
Create queues, see what's ready, in flight and delayed, send messages, and receive and acknowledge them as a worker
Functions
Create and run functions; manage schedules and triggers
Users, Roles
Accounts, role grants, user attributes, custom roles with row filters, hidden and masked fields, MFA resets
Audit Trail
Security events, filterable by user, action and time
Quarantine
Files the malware scanner flagged: what matched, release or delete
Plugins
Loaded plugins, their state and deliveries
Logs
The server log, tailed live
Configuration
AI, chat, sharing and quota settings for the whole lattice: write-only secrets, AI usage and cost estimates, each hex's applied version, history and rollback
Settings
This hex's runtime settings and its effective configuration
Account
Your password, MFA and API keys

Users, Roles, Audit Trail, Plugins, Logs and Settings appear only for roles that hold the matching permission.