Install & run

Run the single-node NYXDB container, understand image and binary defaults, inspect capabilities, or build the engine from source.

The supported deployment is one all-in-one nyxdb process. Docker is the shortest path; a source build is useful for development and for pinning the engine and clients to the same revision.

Run the container image

docker pull ghcr.io/nyxl-io/db:edge

docker run --name nyxdb --rm \
  -p 127.0.0.1:7777:7777 \
  -v nyxdb-data:/var/lib/nyxdb \
  ghcr.io/nyxl-io/db:edge

The image runs as the non-root nyxdb user (UID/GID 10001) and its entrypoint is equivalent to:

nyxdb --host=0.0.0.0 --port=7777 --data-dir=/var/lib/nyxdb

The named volume persists catalog records, DML journal data, checkpoints, and immutable parts. Removing the container does not remove the volume.

Image tags and provenance

NYXDB is currently pre-GA, so use edge for the newest validated main build or pin a source-SHA tag for repeatability.

Tag	Publication contract
`edge`	Newest validated `main` commit; mutable.
`sha-<7>` / `sha-<12>`	One validated source commit; immutable deployment pin.
`<major>.<minor>.<patch>`	Published from a matching stable Git tag when stable releases begin.
`<major>.<minor>` / `latest`	Move only to the highest stable tag in that release line.
`<tag>-asan`	AddressSanitizer/UndefinedBehaviorSanitizer diagnostic flavor of the same source.

The image labels record the source revision, build flavor, dependency fingerprint, compiler, deployment profile, and unsupported HA/replication boundary. Inspect the exact artifact before promotion:

docker image inspect ghcr.io/nyxl-io/db:edge \
  --format '{{ json .Config.Labels }}'

Prefer a SHA tag in production-like environments; edge is intentionally a moving integration artifact.

Container defaults vs native defaults

The container and locally-built binary have deliberately different safe defaults.

Setting	Container image	Native `nyxdb` binary
Bind address	`0.0.0.0`	`127.0.0.1`
Port	`7777`	`7510`
Data directory	`/var/lib/nyxdb`	None
Restart persistence	Enabled when the volume is retained	Disabled unless `--data-dir` is supplied

Running the native binary without --data-dir is an in-memory development mode: nothing survives restart. Supplying --data-dir enables local catalog and DML persistence. It does not add replication or high availability.

Inspect the binary contract

The binary can describe its deployment boundary without starting the server:

docker run --rm ghcr.io/nyxl-io/db:edge --capabilities
docker run --rm ghcr.io/nyxl-io/db:edge --readiness

--capabilities emits versioned JSON. --readiness (also --health) checks the executable's compiled role capability; it does not validate startup configuration or act as a live socket health check. Current clients use the protocol-level ping operation for a live probe. If an older server needs a SELECT 1 probe, configure that separately—the current wire-ping client does not fall back to SQL automatically.

Build from source

Requirements:

CMake 3.30 or newer and Ninja;
a C++23-capable compiler;
vcpkg with VCPKG_ROOT set;
Linux for the production target (macOS is supported for development, subject to Apple Clang's C++ library limitations).

git clone https://github.com/NYXL-io/db.git
cd db

cmake --preset debug
cmake --build cmake-build-debug -j 8
ctest --test-dir cmake-build-debug --output-on-failure

Run the native binary with explicit persistence:

./cmake-build-debug/nyxdb \
  --host=127.0.0.1 \
  --port=7510 \
  --data-dir="$PWD/.nyxdb-data"

For an optimized build and generated API documentation:

cmake --preset release -DNYXDB_BUILD_DOCS=ON
cmake --build cmake-build-release -j 8
cmake --build cmake-build-release --target nyxdb-docs

First queries — execute verified table, stream, and transform examples.
Capabilities & status — evaluate the current production boundary before deployment.
Operations — durability, backup, storage, memory, and observability.