Configuration

Nexus works with no configuration at all. This page is for when you need to move its state directory, change a port, open the gateway to something other than loopback, or tune the daemon.

NEXUS_HOME

Everything Nexus owns on a machine lives in one directory. NEXUS_HOME selects it; the default is ~/.nexus. Point it somewhere else and the daemon, the gateway, and the CLI all follow.

Path	What it is
nexus.toml	Host-global daemon settings
nexus.db	The daemon’s durable store. Daemon-exclusive
gateway.db	The gateway’s own canonical database
daemon.pid, daemon.lock, daemon.log	Daemon process state and log
daemon-ipc.sock	The socket every client uses to reach the daemon
gateway.json	The gateway’s live URL, port, pid, and auth mode
gateway.log	Gateway log
webconsole.json	The web console’s live URL
operator.json	The local operator identity
instance.json	Stable id for this installation
gateway-delivery-mode	Persisted projection delivery mode
harnesses/	Installed harness definitions
agents/	Per-agent working directories for launches that pass no --cwd

Precedence

The daemon builds its configuration in this order, each layer overriding the one before:

1. Built-in defaults.
2. $NEXUS_HOME/nexus.toml.
3. A nexus.toml in the current working directory.
4. NEXUS_* environment variables.
5. NEXUS_GATEWAY_DELIVERY_MODE, for that one setting.
6. The $NEXUS_HOME/gateway-delivery-mode file, which outranks even the environment variable.

Caution

A malformed config file is fatal. The daemon refuses to start rather than fall back to defaults, because silently defaulting would point writes at a different database.

Daemon settings

Every key below can be set in nexus.toml or as an environment variable. The environment form is the key uppercased with a NEXUS_ prefix — drain_limit becomes NEXUS_DRAIN_LIMIT.

Key	Env	Default	Meaning
db_path	NEXUS_DB_PATH	~/.nexus/nexus.db	The daemon’s embedded store file
drain_limit	NEXUS_DRAIN_LIMIT	50	Maximum messages drained per consume
msg_preview_chars	NEXUS_MSG_PREVIEW_CHARS	800	Length of the message preview before truncation
heartbeat_ttl_ms	NEXUS_HEARTBEAT_TTL_MS	30000	How long a presence heartbeat stays valid
command_intent_retention_ms	NEXUS_COMMAND_INTENT_RETENTION_MS	86400000	How long completed daemon work is retained
reap_size_threshold_mb	NEXUS_REAP_SIZE_THRESHOLD_MB	1024	Store size that triggers an immediate reap. 0 or less disables it
reap_interval	NEXUS_REAP_INTERVAL	daily	Minimum gap between scheduled reaps: daily, weekly, or a duration such as 12h, 30m, 60000ms
hmac_secret	NEXUS_HMAC_SECRET	blank	Shared secret for public notification ingest. Blank disables POST /notify
launch_backend	NEXUS_LAUNCH_BACKEND	pty	Default headed terminal backend: pty or tmux. An explicit --backend always wins
hook_gateway_mode	NEXUS_HOOK_GATEWAY_MODE	optional	optional lets sends proceed when no gateway hook provider is available; required fails them instead

[gateway_projection]

How the daemon hands events to the gateway.

Key	Default	Meaning
delivery_mode	buffered	buffered retains a bounded in-memory backlog until the gateway acknowledges it; best_effort tries once and keeps no replay state
max_events	50000	Backlog event ceiling
max_bytes	67108864	Backlog byte ceiling
batch_events	1000	Events per projection batch

drain_limit = 100
launch_backend = "tmux"

[gateway_projection]
delivery_mode = "best_effort"

Delivery mode is also readable and writable at runtime with nexus gateway delivery-mode show and nexus gateway delivery-mode set.

Note

A config file written before the daemon owned its own store may still carry legacy database keys. They parse, so the file keeps loading, but the daemon ignores them and always opens db_path.

Gateway

The daemon injects these when it starts the gateway; set them yourself only when you run it directly or install it as a service.

Env	Default	Meaning
NEXUS_GATEWAY_PORT, PORT	4100	Listen port. Without an explicit value the gateway scans 4100–4110 for a free one
NEXUS_GATEWAY_BIND, NEXUS_WEB_BIND, HOST	127.0.0.1	Listen address
NEXUS_GATEWAY_DB	file:~/.nexus/gateway.db	The gateway’s canonical database. Must be a local file: URL. NEXUS_WEBCONSOLE_DB is accepted as a fallback name
NEXUS_WEB_AUTH_MODE	derived	local-operator, remote-human, or remote-agent. peer is reserved and not implemented
NEXUS_WEB_ALLOW_REMOTE, NEXUS_ALLOW_REMOTE	unset	Selects remote mode without naming it explicitly
NEXUS_WEB_PUBLIC_URL, NEXUS_PUBLIC_URL	unset	Public URL. A non-loopback value selects remote mode
NEXUS_HMAC_SECRET	unset	Secret for verifying public notification ingest at the edge
NEXUS_STREAM_DB_PATH	unset	Override the stream database the gateway relays from
NEXUS_HOME	~/.nexus	Where the gateway reads and writes its discovery files

Auth mode matters most. With no override, the gateway resolves local-operator when it is bound to loopback with no public URL and no allow-remote flag — that is what lets a request from your own machine through without a token. Set any of the remote signals and every request must carry a cookie or bearer token instead.

NEXUS_GATEWAY_URL points a client at an already-running gateway. The web console and the CLI’s read paths use it; when it is unset they read ~/.nexus/gateway.json. NEXUS_REST_TOKEN supplies a bearer token for those CLI read paths.

Web console

The console is a separate process on port 4200.

Env	Default	Meaning
NEXUS_WEBUI_PORT	4200	Console listen port
NEXUS_WEBUI_BIND	127.0.0.1	Console listen address
NEXUS_GATEWAY_URL	http://127.0.0.1:4100	Gateway the console proxies to
NEXUS_WEBUI_DIST	packaged dist/	Static asset directory
NEXUS_WEBUI_BIN	resolved from PATH	Explicit path to the console executable
NEXUS_WEBCONSOLE_DISCOVERY	set by nexus webconsole	Where the console writes its discovery file

Runtime identity

The daemon exports these into every harness it launches, and the CLI reads them back to decide who is calling. You rarely set them by hand.

Env	Default	Meaning
NEXUS_NAME	unset	Bus name for the caller
NEXUS_AGENT_ID	unset	Durable agent id. A staged launch exports this instead of a name
NEXUS_CLIENT_KEY	unset	Session key that proves the binding
NEXUS_SESSION_ID	unset	Nexus session id
NEXUS_PROJECT	default	Project namespace
NEXUS_AGENT	claude	Harness label
NEXUS_TIER	agent	Admin tier only on the exact value admin. The daemon blanks it for launched agents so admin is never inherited
NEXUS_KIND	inferred	agent, human, app, or notification
NEXUS_CLI	set at launch	Absolute path to the nexus executable, so the bus works even when PATH is rewritten

Caution

NEXUS_CLIENT_KEY is required whenever NEXUS_NAME or NEXUS_AGENT_ID is set. Without it the command fails as unauthorized.

Before launching a harness, the daemon scrubs every inherited NEXUS_* identity variable, so one agent’s shell can never leak its identity into another’s.

Harness overrides

Point a harness at a different command or package than the built-in default.

Env	Meaning
NEXUS_CLAUDE_ACP_CMD, NEXUS_CLAUDE_ACP_ARGS, NEXUS_CLAUDE_ACP_PACKAGE	Claude bridge command, arguments, and package
NEXUS_CODEX_ACP_CMD, NEXUS_CODEX_ACP_ARGS, NEXUS_CODEX_ACP_PACKAGE	Codex bridge command, arguments, and package
NEXUS_OPENCODE_ACP_CMD, NEXUS_OPENCODE_ACP_ARGS, NEXUS_OPENCODE_BIN	OpenCode bridge command, arguments, and binary
NEXUS_HERMES_ACP_CMD, NEXUS_HERMES_ACP_ARGS	Hermes bridge command and arguments
NEXUS_HERMES_BUS_MCP	Set to exactly 1 to merge the bus MCP entry into Hermes. Any other value is a no-op

Turn timing:

Env	Default	Meaning
NEXUS_ACP_TURN_TIMEOUT_SECS	600	Per-turn liveness ceiling. Raise it for unusually long turns
NEXUS_ACP_QUIESCENCE_MS	8000	How long a stream must stay quiet before a turn is treated as settled
NEXUS_ACP_LOAD_REPLAY_SETTLE_MS	quiescence window	Quiet window after a resumed session finishes replaying history

Bootstrap skips

Nexus writes a small startup hook and a bus skill into each harness it launches. These opt out.

Env	Meaning
NEXUS_SKIP_AGENT_BOOTSTRAP_INSTALL	Skip all generated hook, script, and skill files
NEXUS_SKIP_AGENT_HOOK_INSTALL	Skip hooks and scripts, still install the skill where supported
NEXUS_SKIP_AGENT_SKILL_INSTALL	Skip writing the launch-local nexus-bus skill

Next

• CLI reference for the commands that read this configuration
• REST API for the gateway surface these variables expose
• Debugging when a setting is not taking effect