06. Docs

Everything in
one place.

Reference documentation for every asanaDB component — server, CLI, MCP server, Admin UI, and the Compository document store.

[asanadb] [asanadb-admin] [asanadb-mcp] [Admin UI] [Compository]

asanadb

The graph database server. TinkerPop3-compliant, LMDB-backed, no JVM required. Accepts connections on a configurable TCP port and a Unix domain socket (UDS) for local-process communication.

Quick Start

# start with defaults (port 8080, data in ./data/)
asanadb

# custom config file
asanadb --config /etc/asanadb/config.yaml

# named instance (multi-tenant)
asanadb --instance production

Flags

--config, -c <path> Path to YAML config file

--instance <name> Named instance for multi-tenant deployments

--map-size <bytes> LMDB map size (supports KB/MB/GB suffixes, e.g. 4GB)

--uds-path <path> Unix domain socket path (default: /tmp/asanadb.sock)

--no-uds Disable the Unix domain socket

--no-wal Disable write-ahead log (not recommended in production)

-v, --version Print version and exit

Config File (YAML)

bind_address: "127.0.0.1"
port: 8080
map_size: "4GB"

asanadb-admin

Command-line administration tool. Connects to a running asanadb instance via the Unix domain socket (UDS) by default — no network port required.

Commands

# verify database integrity
asanadb-admin check

# export all data to GraphSON
asanadb-admin export --output backup.json

# import from GraphSON
asanadb-admin import --input backup.json

# bulk import from CSV
asanadb-admin import_file --file data.csv

# import from Apache GraphSON (APOC format)
asanadb-admin import_file --file export.apoc.json

asanadb-mcp

The MCP (Model Context Protocol) server. Bridges AI tools — Claude, Gemini, Cursor, any MCP-capable client — to the asanaDB graph store. Runs locally on 127.0.0.1 by default. Supports federated deployment via --central (client) and --public (server) modes, both secured with automatic mTLS.

Local

Default mode. AI tools on the same machine connect to 127.0.0.1. No certs, no config.

--central

Connect this MCP instance to a remote central server. mTLS certs auto-provisioned via Sigil on first run.

--public

Run as a federation server on 0.0.0.0. Requires mTLS — refuses to start without certs. Server-to-server only; AI tools never connect here directly.

Quick Start

# local mode — AI tools point to http://localhost:8080
asanadb-mcp

# connect to a central (remote) MCP server — Developer license required
asanadb-mcp --central tcp://10.0.0.1:8443

# run as a federation server — mTLS is mandatory
asanadb-mcp --public --http-port 8443

Flags

--http-port <port> HTTP port for local AI tool connections (default: 8080)

--db-name <name> Database name / tenant to connect to

--db-path <path> Path to the asanadb Unix domain socket

--remote <path> Proxy to a standalone asanadb engine daemon instead of a local database — UDS path or tcp://host:port (Developer license required for tcp://)

--central <tcp://host:port> Connect to a remote central MCP server (Developer license required)

--public Enable federation server mode on 0.0.0.0 (mTLS required)

--cert-dir <path> Directory for mTLS certs (default: ~/.asanasoft)

--sigil-url <url> Sigil endpoint for automatic cert provisioning

A Note on --remote

--remote is unrelated to federation — it proxies this MCP instance straight to a standalone asanadb engine daemon over its own wire protocol, not to another asanadb-mcp instance.

A Unix domain socket connection needs no TLS — it's local and filesystem-permission-scoped. A tcp:// connection is plaintext by design: asanadb does not implement TLS for this link itself. We strongly recommend putting a TLS-terminating reverse proxy (e.g. Caddy) in front of the engine daemon's TCP port if it crosses an untrusted network — but it isn't required. If you're fine connecting over a trusted network, or just want to use a UDS path, that's a supported choice too.

Federation Architecture

AI Tool ──MCP (HTTP, plain)──► asanadb-mcp (local, 127.0.0.1)
                                      │
                            --central tcp:// (mTLS)
                                      │
                                      ▼
                            asanadb-mcp --public (remote MCP Server, 0.0.0.0)

AI tools never connect to a --public instance directly. The public port is server-to-server only, always mTLS.

Trust on this link comes from the mTLS client certificate and its Sigil-issued license binding, not from hostname matching — federation peers are known by license identity, not by DNS name, so the connection address is not checked against the certificate's subject.

Admin UI

A native desktop application for browsing and managing your asanaDB graph. Built with Flutter. Connect it to a running asanadb-mcp instance.

Graph Explorer

Browse vertices and edges with a live graph view. Resizable split between list and detail panels.

Node Management

Create, edit, and delete nodes with confirm dialogs. Accent colors for node type distinction.

Import / Export

Bulk import from CSV, GraphSON, and APOC format. Export the full graph to JSON.

Connecting

The Admin UI connects to asanadb-mcp. Start the MCP server first, then open the Admin UI and enter http://localhost:8080 (or your configured port). The Admin UI is available for macOS. Linux and Windows versions are coming soon.

Compository

asanaDB's document store, built directly into the graph engine. Store rich nested documents — objects, arrays, primitives — as first-class graph vertices. The Compository reconstructs them on read via recursive edge traversal, so you get back exactly what you stored.

Nested Objects

Property values prefixed object: are stored as linked child vertices. Deep or shallow reads — your choice.

Ordered Arrays

Arrays are stored as array: edges with seq properties. Reconstruction sorts by seq, preserving insertion order.

Shallow / Deep

ls returns shallow stubs (_id, _class, key). retrieve returns the fully reconstructed document including all nested objects and arrays.

Wire Protocol

The Compository speaks newline-delimited JSON over a plain TCP connection (default 127.0.0.1:8080). Requests are a JSON object on one line; responses are {"status":"ok","message":...}. See client libraries for ready-made SDKs.

// store (omit "_id" — the server assigns one and returns it)
→ {"op":"store","label":"Article","entity":{"slug":"hello-world","title":"Hello World"}}
← {"status":"ok","message":1}

// retrieve by id
→ {"op":"retrieve","id":1}
← {"status":"ok","message":{"_id":1,"_class":"Article","slug":"hello-world","title":"Hello World"}}

// retrieve by key (when a key field is registered)
→ {"op":"retrieve","key":"slug","value":"hello-world"}
← {"status":"ok","message":{"_id":1,"_class":"Article","slug":"hello-world","title":"Hello World"}}

// list (shallow)
→ {"op":"ls"}
← {"status":"ok","message":[{"_id":1,"_class":"Article"},...]}

// delete
→ {"op":"delete","id":1}
← {"status":"ok","message":"Vertex deleted"}

Internal Fields

_id Integer vertex ID. Always assigned by the server on store and returned in the response, even if omitted from the request.

_class Vertex label / document type (e.g. Article, Person). Set automatically from the store label.

_key Name of the user-defined key field, if registered.

asanaDB v0.16.0

Client SDKs → Downloads →