Configuration

A node is configured with flags on gnarl start. There is no config file to write, and nothing is read from the working directory.

gnarl start --mesh-scope private --mesh-name my-mesh --replicas 2

Defaults are chosen so that gnarl start with no flags is a working single-machine node.

Node

Flag	Default	Description
`--port <PORT>`	`8080`	HTTP port (API and Console)
`--data-dir <PATH>`	`~/.lucenia`	Identity, claims, and local state
`--udp-port <PORT>`	`0`	UDP discovery port. `0` picks 43301 for LAN/private, random otherwise. Override to run two nodes on one machine.
`--headless`	off	API only — do not serve the Console
`--desktop`	off	Background-friendly defaults plus the system tray
`--no-tray`	off	Suppress the tray even in `--desktop` (or set `LUCENIA_NO_TRAY=1`)

Flag	Default	Description
`--mesh-scope <SCOPE>`	—	`private` (named mesh, scoped WAN discovery) or `public` (explicit global participation)
`--mesh-name <NAME>`	—	Required with `--mesh-scope private`
`--single-node`	off	No networking at all
`--dev-mesh`	off	Loopback discovery, for development
`--seed-peers <ADDRS>`	—	Comma-separated UDP addresses for cross-subnet discovery. An escape hatch for air-gapped deployments.
`--admit-peer <NODE_ID>`	—	Pin a 64-hex node ID that may join. Repeatable. Private scope only.
`--mesh-admit-peers <FILE>`	—	Path to a file of admitted node IDs, one 64-hex ID per line (`#` comments allowed). Combines with `--admit-peer`. Private scope only.
`--no-cloud-relay`	off	Do not use the relay for peers behind NAT
`--no-upnp`	off	Do not attempt UPnP port mapping
`--relay-url <URL>`	—	Use a specific relay

A mesh name is a partition, not a fortress

--mesh-name alone separates traffic; it does not authenticate anyone. Pin node IDs with --admit-peer for anything you care about.

Flag	Default	Description
`--replicas <N>`	`2`	Desired replicas per locally owned claim
`--no-replicas`	off	This node will not replicate remote claims
`--durability <MODE>`	`accepted-only`	`accepted-only` lets visibility precede local fsync; `local-sync` gates commit eligibility on it. Local WAL durability, not fabric quorum.
`--edge`	off	Edge companion: advertise edge capability, skip foreign primary placement, longer anti-entropy interval
`--check-in-interval-secs <N>`	`5` (`60` on `--edge`)	Anti-entropy / check-in interval

Flag	Default	Description
`--max-disk-gb <N>`	unlimited	Local disk budget. New segment writes are refused at the ceiling; existing content-addressed blobs stay readable.
`--max-memory-mb <N>`	—	Not yet enforced
`--max-cpu-cores <N>`	—	Not yet enforced

Flag	Default	Description
`--no-tls`	off	Plain HTTP. Not recommended beyond localhost.
`--tls-cert <PEM>` / `--tls-key <PEM>`	self-signed	Supply your own certificate
`--enable-rbac`	off	Capability-token auth on the `/v1` data plane. Redundant on a private mesh, which enables RBAC by default, and refused on a public mesh, which stays open by design.
`--rbac-issuer-key <PATH>`	`<data-dir>/rbac/issuer_ed25519.bin`	RBAC issuer Ed25519 key
`--http-rate-limit <N>` / `--http-rate-limit-burst <N>`	`600`/min, burst `60`	Per-IP limits
`--no-http-rate-limit`	off	Disable the limiter — useful when benchmarking, since the default masks the engine ceiling
`--http-trust-forwarded`	off	Trust `X-Forwarded-For` (only behind a proxy you control)

--output <text\|json\|ndjson> is global, not per-command: an agent driving the CLI asks for JSON once and every command answers the same way.

gnarl --output json index list

geo_point and other Java-backed field types need a classpath:

gnarl start --java-classpath 'java/shard-worker/build/install/shard-worker/lib/*'

No JDK is bundled. Text, vector, and agent memory are pure Rust and need none.

Most configuration is flags. These environment variables also apply:

Variable	Purpose
`LUCENIA_NO_TRAY`	Same as `--no-tray`
`LUCENIA_EMBED_ENDPOINT` · `LUCENIA_EMBED_MODEL` · `LUCENIA_EMBED_API_KEY`	Memory embedding provider. Overrides the Console setting when set.
`LUCENIA_UI_DIST`	Path to the Console bundle, when serving it from somewhere unusual