Configure¶
All settings live in one file, ganglion.yaml, beside the database. The repository ships an annotated copy with every default.
cp ganglion.example.yaml ganglion.yaml
Every key is optional. An unknown key stops the node at start and the error names the key, so a typo never goes unnoticed. If you start the node with --config, that file must exist. Without it, the node looks for ganglion.yaml beside the database and uses defaults when it is missing.
The minimum¶
Set three things.
1. The bot token. The default already reads it from an environment variable:
telegram:
token: env:TELEGRAM_BOT_TOKEN
2. The admin: you. Use your numeric Telegram user id:
telegram:
admin: telegram:user:123456
Without an admin nobody can use the bot.
3. A model. Without a models section the agent is off and the bot only echoes. The default example uses the claude CLI:
models:
providers:
- {name: claude, type: claude-cli}
models:
- {id: sonnet, provider: claude, name: sonnet, tools: true, context: 200000}
- {id: haiku, provider: claude, name: haiku, tools: true, context: 200000}
purposes:
chat: [{model: sonnet, effort: medium}, {model: haiku}]
The chat purpose is required. See Models for more.
To check that Telegram works before you set up a model, run a node with only a token and an admin. It echoes your messages.
Secrets¶
A secret is never written in the file. A field that takes one holds a reference:
env:NAMEreads the environment variableNAME, or the file named byNAME_FILE.store:NAMEreads a secret from the node's own encrypted store.
A literal value in such a field stops the node at start.
Manage the store with the ganglion secret command. Run it as the node's user, against the same database. The value is read from standard input, never from an argument:
printf %s "$TOKEN" | ganglion secret set --db ganglion.db TELEGRAM_BOT_TOKEN
ganglion secret list --db ganglion.db
ganglion secret rm --db ganglion.db TELEGRAM_BOT_TOKEN
Then point the file at it with token: store:TELEGRAM_BOT_TOKEN. list shows names, dates and owners, never values. A module's own secrets use --module <name>. Values from store: are read at start, so restart the node after changing one.
Never paste a secret into the Telegram chat as plain text. To hand one over from your phone, let the node ask for it: see Entering a secret.
The master key¶
The store is encrypted with a key. By default the node creates master.key beside the database at its first start (mode 0600). Or you can supply the key yourself in GANGLION_MASTER_KEY (base64 of 32 random bytes, made with openssl rand -base64 32) or in a file named by GANGLION_MASTER_KEY_FILE.
Keep the key. A database without its key yields no secrets. If the key does not fit the database, the node still starts, but the store is locked and every stored secret reads as unset. /status says so. Give the node the old key back, or send /secrets reset to drop the stored secrets and enter them again.
Where the data goes¶
The data directory is the folder that holds the database. By default:
| What | Where |
|---|---|
| Database | ganglion.db (plus -wal and -shm files while running) |
| Configuration | ganglion.yaml |
| Master key | master.key |
| Logs | logs/ |
| Persona, memory, module sources | workspace/ |
| Installed module files | modules/ |
workspace/ is the agent.workspace setting, relative to the folder the node starts in. It sits beside the database when you start the node from the data directory, as the image does.
Pick the database path with --db or GANGLION_DB, and the configuration with --config or GANGLION_CONFIG. In the container image everything is under /data.
Next: your first conversation. Every setting is listed in the configuration reference.