> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ollim.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration reference
> Configure ollim-bot with environment variables and understand the data directory.
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. |
| `OLLIM_DATA_DIR` | No | `~/.ollim-bot` | Override the [data directory](/configuration/data-directory). Must be set as a shell env var — `storage.py` is imported before `load_dotenv()`, so values in `.env` are ignored. Useful for running a second instance side-by-side. |
| `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](/development/troubleshooting#missing-environment-variables)
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.
```bash title=".env" theme={null}
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`](/core-usage/slash-commands#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 / ` | Extended thinking for the main session |
| `thinking.fork` | thinking mode | `adaptive` | `off / adaptive / ` | 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](/core-usage/permissions) |
| `auto_update` | boolean | `off` | `on / off` | Auto-pull, upgrade tool install, and restart when a new `v*` tag is published |
| `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 |
| `google_calendars` | string | `primary` | Comma-separated calendar IDs | Calendars queried by [`ollim-bot cal`](/integrations/google-calendar#configuring-which-calendars-to-query). First entry is the default for write operations. |
| `google_task_list` | string | `@default` | Google Tasks list ID | Task list used by [`ollim-bot tasks`](/integrations/google-tasks#configuring-the-task-list) |
Update detection is semver-tag based — the bot fetches tags from `origin` and compares the current version to the latest `v*` tag by version sort (`git tag -l "v*" --sort=-version:refname`). Untagged commits on `main` do not trigger auto-updates; releases only ship on a new `v*` tag. Use [`/version`](/core-usage/slash-commands#version) to see the currently running version.
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.
The `/config` slash command's dropdown only exposes a subset of keys for
quick edits. `google_calendars` and `google_task_list` are not in the
dropdown — edit `~/.ollim-bot/state/config.json` directly to change
them. Run `/config` with no parameters to see every key's current
value.
## 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.
```yaml title="~/.ollim-bot/tool-policy.yaml" theme={null}
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](/configuration/file-formats#tool-policy-tool-policyyaml)
for the full schema.
## Data directory
All persistent data lives in `~/.ollim-bot/`. See
[Data directory](/configuration/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, webhooks, and skills are stored as `.md` files with YAML frontmatter:
```yaml title="routines/morning-briefing.md" theme={null}
---
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):
```json title="session_history.jsonl" theme={null}
{"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`](/core-usage/slash-commands#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](/getting-started/google-integration) for the full
credential setup process.
## Next steps
Detailed layout of the \~/.ollim-bot/ directory.
YAML frontmatter specs for routines, reminders, webhooks, and skills.
Running your own instance of ollim-bot.
Install ollim-bot and create a Discord bot.