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 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 themcurl 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.
What You're Looking At
- 1Only 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.
- 2Live Figures
Documents in memory and on disk, tessellations, memory and disk against their budgets, writes and reads per minute, uptime and version.
- 3Activity, 15 Minutes to 6 Hours
Documents per tessellation, operations per minute, or storage over time. The history survives restarts.
- 4Vertex 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.
- 5The 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
- 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.
