Configuration #

All runtime configuration for niri lives in two TOML files passed on the command line:

coral --config /path/to/config.toml --secrets /path/to/secrets.toml.env

Both flags are optional. When omitted, the values below fall back to their defaults. Keys in the secrets file are deep-merged on top of the config file, so a key declared in both resolves to the secrets value.

Why two files? Secrets are kept out of the main config (and the process environment) so spawned subprocesses — including the agent's shell tool — never inherit credentials. secrets.toml.env should be permission-restricted and excluded from version control.

The systemd module (flake.nix) exposes matching options:

services.coral = {
  enable      = true;
  configFile  = "/etc/coral/config.toml";
  secretsFile = "/etc/coral/secrets.toml.env";
};

Both are nullable; when set, they're appended to the service's ExecStart.

---

[server] #

Key	Default	Description
port	3000	HTTP port the server listens on.

[agent] #

Key	Default	Description
name	"niri"	Display name injected into the summarizer prompt and system grounding.
env	"default"	Runtime tag. Set to "local" to skip the primary model entirely and run on the fallback only.

---

[model] — primary #

Used for normal agent turns.

Key	Default	Description
provider	(required)	Provider name in the pi registry — e.g. "openrouter", "openai", "deepseek". Resolves base URL and reasoning flags. Required unless agent.env = "local".
name	(required)	Model id — e.g. "deepseek/deepseek-r1", "claude-sonnet-4-5". Required unless agent.env = "local".
base_url	(from registry)	OpenAI-compatible base URL override for unlisted/self-hosted endpoints.
tool_choice	"required"	"required", "auto", or "none".
enable_thinking	true	Extended reasoning on models that support it.
thinking_effort	"low"	Reasoning budget: "minimal", "low", "medium", "high", "xhigh".
api_key (secret)	(required)	API key for the primary endpoint. Place this in secrets.toml.env.

[fallback] #

Used when the primary endpoint is unreachable or agent.env = "local". Defaults target a small, cheap model suitable for local LM Studio / Ollama.

Key	Default	Description
provider	(inferred)	Provider for the fallback model. Inferred from base_url if omitted (localhost → lm-studio).
model	"zai-org/glm-4.7-flash"	Fallback model id.
base_url	(from registry)	Base URL for the fallback model.
tool_choice	"required"	"required", "auto", or "none".
n_ctx	4096	Declared context window size used for context-limit enforcement.
context_margin	256	Token headroom reserved before a soft nudge is issued.
hard_overflow_tokens	1024	Tokens above the window that trigger a hard prompt truncation.
enforce_context_limit	true if base URL is localhost	Whether to enforce the context window limit.
referer	—	HTTP-Referer header on fallback requests (OpenRouter attribution).
title	—	X-Title header on fallback requests.
api_key (secret)	—	API key override for the fallback endpoint.

[summary] #

Optional dedicated summarizer model. Falls back to the primary if not configured.

Key	Default	Description
provider	(inferred)	Provider for the summary model.
model	(uses primary)	Model id. Leave empty to reuse the primary.
base_url	(from registry)	Base URL override.
referer	—	HTTP-Referer header on summary requests.
title	—	X-Title header on summary requests.
api_key (secret)	—	API key override for the summary endpoint.

---

[embeddings] #

Embeddings power semantic memory search. Set api_key to enable; without it the embedding client is disabled and memory search falls back to keyword matching.

Key	Default	Description
model	"google/gemini-embedding-2-preview"	Embedding model id.
dimensions	3072	Output vector dimensions. Must match the database schema; changing it requires rebuilding memory_chunk_vec, memory_prototype_vec, and embedding meta.
base_url	"https://openrouter.ai/api/v1"	OpenAI-compatible base URL.
referer	—	HTTP-Referer header on embedding requests.
title	—	X-Title header on embedding requests.
api_key (secret)	—	API key for the embedding endpoint.

---

[context] #

Token / compaction thresholds.

Key	Default	Description
token_nudge_threshold	120000	Tokens at which the runner hints to the primary model to wrap up before compaction.
fallback_token_nudge_threshold	50000	Same nudge, but for the fallback model's smaller window.
compact_target_tokens	65000	Target post-compaction size.
compact_trigger_tokens	90000	Tokens that trigger automatic compaction.
compact_recent_messages	80	Recent messages retained verbatim during compaction.
compact_chunk_messages	32	Messages summarized per compaction chunk.
compact_summary_max_chars	16000	Hard cap on generated summary length.
idle_compaction_minutes	45	Idle time before background compaction runs. Decimals supported (e.g. 2.5 for 2m30s). Set to 0 to disable.

[runner] #

Key	Default	Description
max_turns	120	Hard cap on LLM turns per wakeup before the runner forces a rest.
max_identical_tool_turns	10	Maximum consecutive turns with the same tool-call signature before the runner bails to break a loop.

---

[container] and [ssh] #

Three execution backends are available: local shell (default), Docker, and SSH. The two override sections are mutually exclusive — setting fields in both throws at startup.

[container] (Docker) #

Key	Default	Description
name	—	Docker container name. Both name and user must be set to activate Docker mode. Commands run as docker exec -i -u <user> -w <cwd> <name> bash -c <cmd>.
user	—	Linux username inside the container. Must be set alongside name.

The harness home (soul, memories, DB) is anchored to the repo-local home/ directory, which should be bind-mounted into the container.

[ssh] #

Key	Default	Description
target	—	SSH destination in user@host form. Setting this activates SSH mode: shell commands run on the remote host via ssh <target> bash -c <cmd>.
identity	—	Path to the SSH private key passed as ssh -i <path>. Omit to use the agent's default key or ~/.ssh/config.

[image_tool] #

Key	Default	Description
max_bytes	150000	Max image size in bytes accepted by image_tool.
root	home/images (local/SSH) or /home/<user>/images (Docker)	Absolute path bounding all image_tool operations. Must start with /.

---

[discord] #

Credentials & identity #

Key	Default	Description
bot_token (secret)	—	Discord bot token. Required for any Discord functionality. Without it the gateway and REST client are both disabled.
bot_user_id	(auto-detected)	Bot user id. Auto-populated from the gateway READY payload on first connect.
scan_channel_ids	[]	Channel ids the bot treats as its inbox. DMs are always included regardless. Example: ["1234567890", "0987654321"].

Gateway (WebSocket listener) #

Key	Default	Description
gateway_enabled	true	Disable the WebSocket gateway entirely. Useful when only REST polling is wanted.
gateway_trace	false	Verbose per-message trace logging (noisy; for debugging).
gateway_raw_fallback	true	Use the raw MESSAGE_CREATE packet handler as a DM fallback for messages discord.js doesn't surface.
gateway_raw_fallback_all	false	Extend the raw fallback to all channel types, not just DMs.
wake_on_event	false	Wake the runner on every ingested guild channel message (not just DMs). DMs always wake.
wake_on_dm	true	Wake immediately on DMs even when wake_on_event is false.

Batch digest (REST polling) #

Key	Default	Description
batch_interval_ms	60000	How often (ms) the server polls Discord for new messages. Minimum 1 000 ms.
batch_max_messages	40	Max messages fetched per channel per poll. Capped at 200.
batch_scan	true	Disable REST batch scanning while keeping the gateway running.
batch_only_configured	true	When true, batch digests only include DMs and channels in scan_channel_ids.
pending_auto_seen_minutes	10	Age in minutes after which a pending Discord item is demoted to "seen" without a response.

REST client #

Key	Default	Description
rest_max_attempts	3	Max retry attempts on transient REST failures (rate limits, 502/503/504). Capped at 10.
rest_retry_base_ms	1000	Base delay for exponential backoff. Min 100 ms, max 30 000 ms.

---

[metrics] #

Key	Default	Description
retention_days	3	Days to retain metrics rows before they are pruned.