Skip to content

Configuration reference

All settings are in ganglion.yaml. Every key is optional and the values below are the defaults. The file is checked strictly: an unknown key stops the node at start and the error names it. For an editor with completion, the example file starts with a line that points to the JSON schema schemas/node.schema.json.

Only the module list and the mcp section change while the node runs. Every other section applies at the next start: send /restart or restart the process.

A field that takes a secret holds env:NAME or store:NAME. See Configure. Where a value is a duration, write it like 8s, 10m or 6h. off turns a feature off where noted.

node

Key Default Meaning
memory_limit none The soft memory limit of the node (GOMEMLIMIT), for example 400MiB. Without it the node takes about 80 % of its container's limit, or none. A GOMEMLIMIT in the environment wins.
tz Europe/Kyiv The IANA time zone that decides where a day starts. It also times reminders and daily limits. Change it.

log

Key Default Meaning
level info debug, info, warn or error.
dir logs/ beside the database The directory of the rotated log files. off writes no files.

metrics

Key Default Meaning
addr 127.0.0.1:9464 The Prometheus endpoint, host:port. off runs none.

http

Key Default Meaning
addr off The node's public listener, host:port. It serves plain HTTP behind a proxy that ends TLS and carries the Telegram webhook and a health route. It is never the metrics endpoint.
public_url none The HTTPS address the outside world reaches the listener at, with no path and no port or one of 443, 80, 88, 8443.

See Telegram updates.

telegram

Key Default Meaning
token env:TELEGRAM_BOT_TOKEN The bot token. The transport does not start without it.
updates polling polling or webhook.
api_url https://api.telegram.org The Bot API's base address.
admin none The admin, as telegram:user:<id>. Missing means nobody can use the bot.
reply auto When an answer quotes the message it answers: auto (in a group, or when newer messages came after it), always or off.
rich true Turn Markdown into Telegram formatting.
reactions.after 8s How long a turn runs before the bot first reacts. off means never.
reactions.dwell 3s How long a reaction stays before the next one.
groups empty Group chats whose members may talk to the bot.

A group entry has chat (a negative number), name and role: family. The node writes the line when you press Allow on the group card:

telegram:
  groups:
    - chat: -1001234567890
      name: Family
      role: family

agent

Key Default Meaning
workspace workspace The directory of the agent's persona and memory. Relative to the working directory. The image uses /data/workspace.
languages beside the database The directory of the language files.
session_idle 6h The silence after which a conversation starts afresh. off never does.
call_timeout 3m How long one model call may take. On the claude CLI route one call runs every tool call of its turn. Not longer than turn_timeout.
turn_timeout 5m How long a whole turn may take.
max_steps 20 How many model calls one turn may make, from 1 to 100. Listing a connected server's tools and turning them on does not spend them.
limits.daily_budget_usd 1 Spend per day. See Models.
limits.daily_turns 300 Turns per person per day.
limits.daily_tokens 1000000 Tokens per person per day.
search.mode auto auto uses Brave when a key is set and DuckDuckGo otherwise; off gives the agent none.
search.brave_key env:BRAVE_API_KEY Key for Brave search. Without one, DuckDuckGo is used.

A 0 or off in a limit turns that one off. limits: off turns all of them off.

sandbox

Key Default Meaning
deny empty Extra paths the command sandbox refuses, on top of its built-in list.
hide_names false Hide the names of denied paths too.

models

The providers, models and purposes. Without this section the agent is off. See Models.

destinations

Names for the conversations a message may be sent to: a group, a forum topic or a private chat. The node writes a line when you ask it in your private chat to name a place.

destinations:
  - name: family-kitchen
    conv: telegram:-1001234567890/45

A name is lowercase letters, digits and dashes, starts with a letter, at most 32 characters, and is not owner.

modules

The modules the node runs and their settings. Installing a module writes to this list.

Key Meaning
name The module's name.
config Its settings, checked against what the module declares.
off Set to turn the module off.
notify_to Where its messages go: owner (your private chat, the default) or names from destinations. Up to 8, each message goes to every one.
modules:
  - name: local/price-watch
    notify_to: [family-kitchen, owner]

mcp

The remote MCP servers the node uses. The section changes only through the assistant's tools: config.propose refuses it, and an edit on the host applies at the next start. See Connecting an MCP server.

Key Default Meaning
page the project's intake page The address of the page a sign-in ends on.
servers.<name>.url The server's https address.
servers.<name>.auth none, oauth or header.
servers.<name>.header The header that carries the key, for auth: header. The key itself is in the secret store, never in the file.
servers.<name>.timeout 30s How long one request may take.
servers.<name>.tools Each approved tool's rule: auto, confirm or forbidden.
servers.<name>.fingerprint Pins the approved tool list.
mcp:
  servers:
    shop:
      url: https://mcp.example.com/mcp
      auth: oauth
      tools:
        search_products: auto

memory

Key Default Meaning
prompt_budget 24000 The size in characters of the known-facts block of the agent's instructions. Over it, the topics changed longest ago fold to one line.
review.enabled true Read your quiet private chat once for facts the turn missed.
review.quiet 10m How long the chat is silent before it is reviewed.
archive_days 90 How many days an ended conversation stays in the archive, where /resume and the agent's search of past chats find it. A conversation the agent has not reviewed yet stays until it is. Facts the agent remembers are kept. off keeps every conversation.

update

Key Default Meaning
check true Ask once a day for a newer release and tell the admins once per version, with the version, its date and a link. It never installs one: you do, with /update install. Set off to stop the asking. Without a release version (a build from source) and with the database in memory, the node asks nothing.

bus

The node's message bus. By default the node runs a NATS server inside its own process and keeps its files in the bus folder beside the database; it opens no network port. Only a host edit changes this section: the agent cannot. See The message bus.

Key Default Meaning
server embedded embedded runs the server inside the node. external connects to a server, or a cluster, you run.
urls none The external server's addresses, nats:// or tls:// with a host and no user or password. Required for external and refused for embedded.
credentials none The text of a .creds file for the external server, as env:NAME or store:NAME. It is optional, only for external, and is kept in memory, never written to a file.
bus:
  server: external
  urls: [nats://nats.example.com:4222]
  credentials: store:BUS_CREDENTIALS

backup

The daily encrypted backup to an S3-compatible bucket. Without this section there are no backups. Only a host edit changes it: the agent cannot. When the section is there, the first five keys are required. See Backups.

Key Default Meaning
endpoint none The bucket's S3 endpoint, an HTTPS address with a host and no path, such as https://s3.example.com. A plain http address is refused.
region none The signing region the provider names (auto at Cloudflare R2).
bucket none The bucket's name.
access_key_id none The id of the access key. Give the key the right to write into this bucket and no right to delete.
secret_access_key none The access key's secret, as env:NAME or store:NAME. The node does not start while it is not set.
prefix empty The folder in the bucket the copies go to. Empty puts them at the top.
at 03:00 The time of day, HH:MM in node.tz, the backup runs at.
backup:
  endpoint: https://s3.example.com
  region: us-east-1
  bucket: my-node-backups
  prefix: node
  access_key_id: EXAMPLEKEYID
  secret_access_key: env:BACKUP_SECRET_ACCESS_KEY