Configuration reference

All environment variables and credential files that configure ollim-bot. The bot is configured through environment variables loaded from a .env file at the project root. All persistent data lives in ~/.ollim-bot/, which is automatically managed as a git repository — ollim-bot auto-commits changes on each write.

Environment variables

Variable	Required	Default	Description
`DISCORD_TOKEN`	Yes	—	Discord bot token for authentication
`OLLIM_USER_NAME`	Yes	—	Your display name, used in the system prompt and messages
`OLLIM_BOT_NAME`	Yes	—	The bot’s display name
`OLLIM_TIMEZONE`	No	System local	IANA timezone name (e.g. `America/New_York`). Used for timestamps in session history, pending updates, scheduling preambles, and Google Calendar/Gmail. Falls back to system local detection, then UTC.
`WEBHOOK_PORT`	No	—	Port for the webhook HTTP server; omit to disable webhooks
`WEBHOOK_SECRET`	Conditional	—	Bearer token for webhook authentication; required if `WEBHOOK_PORT` is set

If WEBHOOK_PORT is set without WEBHOOK_SECRET, the webhook server will not start. Both must be set together.

All three required variables are validated together on startup. If any are missing, the bot lists all missing vars with hints and exits. See troubleshooting for the exact output.

`.env` file

Place a .env file at the project root. Both config.py and main.py call load_dotenv() to load it.

.env

DISCORD_TOKEN=your-discord-bot-token
OLLIM_USER_NAME=YourName
OLLIM_BOT_NAME=Ollim
OLLIM_TIMEZONE=America/New_York
WEBHOOK_PORT=8420
WEBHOOK_SECRET=a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5

CLI subcommands (routine, reminder, tasks, cal, gmail) do not require DISCORD_TOKEN — it is only loaded when starting the bot.

Runtime configuration

In addition to environment variables, ollim-bot has persistent runtime settings you configure via the /config slash command. ollim-bot stores these in ~/.ollim-bot/state/config.json, and they survive bot restarts.

Key	Type	Default	Valid values	Description
`model.main`	model	SDK default	`opus / sonnet / haiku / default`	Default model for the main session
`model.fork`	model	Inherits from main	`opus / sonnet / haiku / default`	Default model for interactive forks
`thinking.main`	thinking mode	`off`	`off / adaptive / <budget>`	Extended thinking for the main session
`thinking.fork`	thinking mode	`adaptive`	`off / adaptive / <budget>`	Extended thinking for interactive forks
`bg_fork_timeout`	integer	`1800`	Any integer	Max background fork runtime (seconds)
`fork_idle_timeout`	integer	`10`	Any integer	Interactive fork idle timeout (minutes)
`permission_mode`	permission mode	`dontAsk`	`dontAsk / default / acceptEdits / bypassPermissions`	Default permission mode
`auto_update`	boolean	`off`	`on / off`	Auto-pull, upgrade tool install, and restart on new commits
`auto_update_interval`	integer	`60`	Any integer	Update check interval (minutes)
`auto_update_hour`	hour (0-23)	`6`	`0-23`	Hour of day to apply updates

Runtime config is separate from environment variables — env vars require a restart, while /config changes take effect immediately. Use env vars for credentials and infrastructure, /config for preferences.

Tool policy

You can extend or override the default tool sets by creating a tool-policy.yaml file in ~/.ollim-bot/. This is useful for granting the agent access to additional tools without editing source code.

~/.ollim-bot/tool-policy.yaml

main_session:
  additional_allowed:
    - "Bash(git status)"
bg_forks:
  additional_allowed:
    - "Bash(ollim-bot cal *)"

Changes take effect without a restart — the file is re-read when its modification time changes. See File formats for the full schema.

Data directory

All persistent data lives in ~/.ollim-bot/. See Data directory for the full layout, file descriptions, and git tracking details.

Storage patterns

ollim-bot uses two storage formats with shared conventions:

Markdown files
JSONL files

Routines, reminders, webhooks, and skills are stored as .md files with YAML frontmatter:

routines/morning-briefing.md

---
id: abc123
cron: "30 8 * * 1-5"
description: Morning briefing
---
Review my tasks and calendar for today, then give me a summary.

Filenames are auto-generated slugs from the message content
The id field in YAML is authoritative — filenames are for human readability
Slug collisions are resolved with numeric suffixes (-2, -3, etc.)
Writes use atomic temp-file-then-rename to prevent corruption
Each write triggers a git commit

Session history uses append-only JSONL (one JSON object per line):

session_history.jsonl

{"event": "created", "session_id": "sess_abc", "timestamp": "2026-02-24T10:00:00"}
{"event": "compacted", "session_id": "sess_abc", "timestamp": "2026-02-24T11:30:00"}

Lines not starting with { are skipped; malformed JSON raises json.JSONDecodeError
Field filtering ensures forward compatibility — unknown fields are ignored when reading
Removals use atomic rewrite (read all, filter, write temp file, rename)
Each write triggers a git commit

Google credentials

Google integration uses file-based credentials rather than environment variables.

File	Source	Description
`~/.ollim-bot/state/credentials.json`	Manual — downloaded from Google Cloud Console	OAuth 2.0 client credentials
`~/.ollim-bot/state/token.json`	Auto-generated after `/google-auth`	OAuth refresh and access tokens

Tokens are refreshed automatically. If a token is revoked, the bot detects it and prompts you to run /google-auth again. See Google integration setup for the full credential setup process.

Next steps

Data directory

Detailed layout of the ~/.ollim-bot/ directory.

File formats

YAML frontmatter specs for routines, reminders, webhooks, and skills.

Self-host ollim-bot

Running your own instance of ollim-bot.

Quickstart

Install ollim-bot and create a Discord bot.

Configuration

Development

​Environment variables

​.env file

​Runtime configuration

​Tool policy

​Data directory

​Storage patterns

​Google credentials

​Next steps

Data directory

File formats

Self-host ollim-bot

Quickstart

Environment variables

`.env` file

Runtime configuration

Tool policy

Data directory

Storage patterns

Google credentials

Next steps