Skip to main content
ollim-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.

​
Environment variables

VariableRequiredDefaultDescription
DISCORD_TOKENYes—Discord bot token for authentication
OLLIM_USER_NAMEYes—Your display name, used in the system prompt and messages
OLLIM_BOT_NAMEYes—The bot’s display name
OLLIM_TIMEZONENoSystem localIANA 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_PORTNo—Port for the webhook HTTP server; omit to disable webhooks
WEBHOOK_SECRETConditional—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.
OLLIM_USER_NAME and OLLIM_BOT_NAME are validated at import time — the process exits immediately if either is missing. DISCORD_TOKEN is checked when the bot subcommand runs.

​
.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.

​
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:
Routines, reminders, and webhooks 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

​
Google credentials

Google integration uses file-based credentials rather than environment variables.
FileSourceDescription
~/.ollim-bot/state/credentials.jsonManual — downloaded from Google Cloud ConsoleOAuth 2.0 client credentials
~/.ollim-bot/state/token.jsonAuto-generated on first authentication flowOAuth refresh and access tokens
See Google OAuth 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, and webhooks.

Self-hosting guide

Running your own instance of ollim-bot.

Discord bot setup

Creating a Discord application and getting your bot token.