- TypeScript 97%
- CSS 2%
- Nix 1%
- JavaScript <1%
- Docker <1%
- 3 more languages <1%
Niri #
Run the server #
npm ci
cp agents/mira.example.toml agents/mira.toml
chmod 600 agents/mira.toml
# edit agents/mira.toml
npm start
The server reads every .toml file in agents/. Files ending in .example.toml are skipped.
Run a client #
cd apps/client
npm run start
The client listens on 0.0.0.0:3002 and runs shell, read_file, edit_file, and image_tool from the client's home directory.
Agent memory #
Memory lives on the server under the agent's home, separate from any attached client:
| Path | Contents |
|---|---|
<home>/soul.md |
The agent's identity and enduring self-description |
<home>/memories/ |
Long-term Markdown memories, including core notes, journals, and people files |
<home>/state/ |
Session, rest snapshot, and failover state |
<home>/niri.db |
The searchable memory index and other durable runtime data |
For example, an agent with home: /home/niri keeps long-term memories in /home/niri/memories.
For routine maintenance, ask the agent to inspect, organize, or repair their own memories using the memory tools. Treat soul.md and memories/ like a private diary: do not read or change them unless the agent asks; it's weird if you do. For backup or recovery, stop the worker and preserve the entire agent home rather than copying only the Markdown files.
Agent TOML specification #
One file in agents/ is one agent. Files ending in .example.toml are skipped.
Keys are literal — write nested values as tables, never as dotted keys.
An agent file describes only what the control plane owns. Everything the agent
runs on — model, fallback, tools, context, Discord, subagents — lives in the
runtime TOML named by config, in the same format a standalone
coral --config … run reads. There is one config dialect, and both ways of
starting a worker feed it the identical file.
Top level #
| Field | Type | Required | Default |
|---|---|---|---|
id |
string matching [a-zA-Z0-9_-]+ |
no | filename without .toml |
name |
string | no | id |
port |
integer 1..65535 |
no | control port plus the file's sorted position |
home |
path | no | data/agents/<id> |
client |
local or an HTTP(S) URL |
yes | — |
workspace |
path | no | repository root; applies to client = "local" |
config |
path, or a list of paths | no | — |
secrets |
path | no | — |
[settings] |
table | no | {} |
Relative home, workspace, config, and secrets paths resolve from the
repository root. A config or secrets path that does not exist fails startup.
config and secrets #
The worker is spawned with these as --config and --secrets flags. config
may be a list: each file is deep-merged over the previous one, so several
agents can share a base file and layer their own differences on top. secrets
is merged last, so a key set in both resolves to the secrets value.
config = ["/etc/coral/config.toml", "/etc/coral/agents/mira.toml"]
secrets = "/run/agenix/coralSecrets"
Credentials reach the worker as files, never as environment variables — the agent's own shell tool inherits that environment.
[settings] #
settings accepts string, number, and boolean values keyed by uppercase
runtime setting names, and becomes the worker's environment. It is for the
settings that are genuinely environment-shaped; anything the runtime reads from
TOML belongs in config. Names the server manages — PORT, HOME,
CORAL_CONFIG, CORAL_SECRETS, and the NIRI_* prefixes — are rejected.
TODO: Promote the remaining active settings into first-party TOML sections for tools, context management, Discord batching/cooldowns, state, and bridges. Remove the settings that have no runtime reader.
Tools and model calls #
| Setting | Staged value | Purpose |
|---|---|---|
IMAGE_TOOL_MAX_BYTES |
1000000 |
Maximum image size accepted by the image tool. |
PRIMARY_TOOL_CHOICE |
auto |
Tool-choice mode for primary model requests: required, auto, or none. |
FALLBACK_TOOL_CHOICE |
auto |
Tool-choice mode for fallback model requests. |
FALLBACK_ENFORCE_CONTEXT_LIMIT |
false |
Enforce the configured fallback context limit before sending a request. |
Context management #
| Setting | Staged value | Purpose |
|---|---|---|
CONTEXT_COMPACT_TRIGGER_TOKENS |
100000 |
Start context compaction at this token estimate. |
TOKEN_NUDGE_THRESHOLD |
120000 |
No current runtime reader. |
CONTEXT_COMPACT_TARGET_TOKENS |
65000 |
No current runtime reader. |
CONTEXT_COMPACT_RECENT_MESSAGES |
80 |
No current runtime reader. |
CONTEXT_COMPACT_CHUNK_MESSAGES |
32 |
No current runtime reader. |
CONTEXT_COMPACT_SUMMARY_MAX_CHARS |
500000 |
No current runtime reader. |
Discord #
| Setting | Staged value | Purpose |
|---|---|---|
DISCORD_GATEWAY_TRACE |
true |
Log gateway tracing details. |
DISCORD_GATEWAY_RAW_FALLBACK |
true |
Use raw gateway events when the normal event path cannot handle an event. |
DISCORD_BATCH_INTERVAL_MS |
8000 |
Interval between Discord batch checks. |
DISCORD_BATCH_ONLY_CONFIGURED |
true |
Limit batches to DMs and configured scan channels. |
DISCORD_PENDING_AUTO_SEEN_MINUTES |
10 |
Mark pending messages seen after this many minutes. |
DISCORD_BATCH_SCAN |
true |
Scan configured channels before building each batch. |
DISCORD_BATCH_MAX_MESSAGES |
120 |
Maximum messages included in one batch. |
COOLDOWN_CHANNELS |
channelId,2000,0400 |
Channel response windows as repeated channelId,startHHMM,endHHMM triples. |
COOLDOWN_TZ |
America/New_York |
Time zone used for cooldown windows. |
DISCORD_WAKE_ON_DM |
true |
No current runtime reader. |
DISCORD_WHITELIST |
Discord user ids | No current runtime reader; use discord.dmWhitelist. |
State and process #
| Setting | Staged value | Purpose |
|---|---|---|
NIRI_MIGRATE_LEGACY_STATE |
true |
Copy root-level session snapshots into the agent state directory once. |
AGENT_UID |
1001 |
No worker runtime reader; used only by the Docker build and Compose configuration. |
AGENT_GID |
1001 |
No worker runtime reader; used only by the Docker build and Compose configuration. |
Bridges #
| Setting | Staged value | Purpose |
|---|---|---|
ANTIGRAVITY_BRIDGE_ENABLED |
Niri: false; Lyra: true |
Start the Antigravity bridge. |
ANTIGRAVITY_BRIDGE_PORT |
8000 |
Antigravity bridge loopback port. |
ANTIGRAVITY_BINARY_PATH |
/home/niri/.local/bin/agy |
Antigravity executable. |
CODEX_BRIDGE_ENABLED |
Niri: true; Lyra: false |
Start the Codex bridge. |
CODEX_BRIDGE_PORT |
8001 |
Codex bridge loopback port. |
CODEX_BRIDGE_MODEL |
gpt-5.6-sol |
Model presented by the Codex bridge. |
CODEX_BRIDGE_REASONING_EFFORT |
low |
Codex bridge reasoning effort. |
Agent ids, worker ports, canonical home paths, Discord tokens, and enabled bridge ports must be unique.
Agent TOML files contain credentials and should use mode 0600. Tool-client endpoints should stay on loopback or a trusted private network.
Check the repository #
npm run typecheck
npm test
npm run build