Install
NamiDB ships as a Python wheel, a server container image, prebuilt binaries and source. They are all the same engine; install the one that matches how you want to run it.
| You want to… | Install |
|---|---|
| Use the graph from Python code, notebooks or tests | Python wheel |
| Run a server other processes connect to over HTTP or Bolt | Docker image or server binary |
| Run one-off queries, backups and vault imports from a shell | namidb CLI |
| Give an AI agent read access to a graph | namidb-mcp |
| Embed the engine in a Rust program | Rust crates |
Python
pip install namidb- Python 3.9 or newer.
pyarrow >= 14is installed as a dependency. - Optional DataFrame extras:
pip install 'namidb[pandas]'(pandas ≥ 2.0) andpip install 'namidb[polars]'(polars ≥ 0.20). - Prebuilt abi3 wheels exist for Linux x86_64 and aarch64, macOS arm64 and x86_64, and Windows x86_64. Other platforms build from the source distribution, which needs a Rust toolchain.
- The wheels include the persistent vector and full-text indexes, so
CREATE VECTOR INDEXandCREATE FULLTEXT INDEXwork out of the box.
Check the install:
python -c "import namidb; print(namidb.__version__)"# 3.3.0Next: Embedded Python and the Python API reference.
Docker
The official namidb-server image is multi-arch (linux/amd64 and
linux/arm64) and is built with vector and full-text search enabled.
| Registry | Image |
|---|---|
| Docker Hub | namidb/namidb-server |
| GitHub Container Registry | ghcr.io/namidb/namidb-server |
Each release is tagged X.Y.Z, X.Y, X and latest. Pin an exact
version in production:
docker pull namidb/namidb-server:3.3.0Run it with a named volume for a durable local store. The server refuses to start without an auth source, so pass a token:
export NAMIDB_AUTH_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8080:8080 \ -v namidb-data:/var/lib/namidb \ -e NAMIDB_AUTH_TOKEN \ namidb/namidb-server:3.3.0 \ --store "file:///var/lib/namidb?ns=prod"curl -s localhost:8080/v0/health# {"status":"ok","namespace":"prod","manifest_version":0,"epoch":0,"writer":"ok",...}What the image sets up:
- The process runs as a non-root user (uid/gid
65532)./var/lib/namidbis pre-created and owned by that user, so a fresh named volume mounted there just works. A bind mount needschown -R 65532:65532 <dir>on the host first. NAMIDB_LISTEN=0.0.0.0:8080,NAMIDB_SPOOL_DIR=/var/tmp/namidb-spool,RUST_LOG=info, and bounded glibc allocator arenas (MALLOC_ARENA_MAX=2).- A built-in
HEALTHCHECKthat probes/v0/livez. It followsNAMIDB_LISTENand switches to HTTPS whenNAMIDB_TLS_CERTorNAMIDB_TLS_KEYis set; if you change the listen address or TLS with command-line flags instead, set the same values as environment variables so the probe sees them.
For a server backed by an S3-compatible bucket, see Docker + MinIO.
Release binaries
Each GitHub release ships prebuilt archives with SHA-256 checksums:
| Archive | Contains | Built with |
|---|---|---|
namidb-server-v3.3.0-<target> | namidb-server | vector-index, text-index |
namidb-v3.3.0-<target> | namidb (CLI) and namidb-mcp | no optional features |
Targets: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu,
aarch64-apple-darwin (.tar.gz) and x86_64-pc-windows-msvc (.zip).
Linux archives are built on Ubuntu 22.04 and need glibc 2.35 or newer; use
the container image or build from source for older systems.
TARGET=x86_64-unknown-linux-gnu # or aarch64-unknown-linux-gnu, aarch64-apple-darwinBASE=https://github.com/namidb/namidb/releases/download/v3.3.0
curl -fsSLO "$BASE/namidb-server-v3.3.0-$TARGET.tar.gz"curl -fsSLO "$BASE/namidb-server-v3.3.0-$TARGET.sha256"sha256sum -c "namidb-server-v3.3.0-$TARGET.sha256"tar xzf "namidb-server-v3.3.0-$TARGET.tar.gz"
./namidb-server --version# namidb-server 3.3.0The CLI archive works the same way and unpacks namidb and namidb-mcp:
./namidb --version # namidb 3.3.0./namidb-mcp --version # namidb-mcp 3.3.0From source
Requires Rust 1.85 or newer.
git clone https://github.com/namidb/namidbcd namidbgit checkout v3.3.0# Same feature set as the official image and release binary:cargo install --locked --path crates/namidb-server --features vector-index,text-index
# Add OIDC/JWT and the external policy hook:cargo install --locked --path crates/namidb-server --features vector-index,text-index,jwt,pdpA plain cargo install without features gives a smaller binary that rejects
CREATE VECTOR INDEX / CREATE FULLTEXT INDEX with HTTP 400.
cargo install --locked --path crates/namidb-clicargo install --locked --path crates/namidb-mcppip install maturincd crates/namidb-pymaturin develop --releasedocker build -t namidb/namidb-server:3.3.0-local -f crates/namidb-server/Dockerfile .| Server feature | Enables |
|---|---|
vector-index | CREATE VECTOR INDEX, DROP VECTOR INDEX, and index-backed vector search |
text-index | CREATE FULLTEXT INDEX, DROP INDEX, and index-backed BM25 |
jwt | --jwt-* flags: OIDC / JWT bearer validation against a JWKS |
pdp | --pdp-url: an OPA-style external policy decision point |