Home / Documentation / Configuration

Configuration reference

All configuration is environment variables plus one JSON whitelist file. Nothing else.

Environment variables

VariableRequiredDefaultDescription
TELEGRAM_BOT_TOKENYes—Bot token from @BotFather
LLM_BASE_URLYes—Any OpenAI-compatible endpoint, e.g. https://api.openai.com/v1
LLM_API_KEYYes—API key for the LLM endpoint
LLM_MODELYes—Model name your endpoint supports (use a vision-capable model for receipt photos)
EXPENSE_DB_PATHNoexpenses.dbSQLite database location
AUTHORIZED_USERS_CONFIG_PATHRecommended—Path to the JSON whitelist of Telegram user IDs. In Docker: /data/authorized-users.json
UNAUTHORIZED_LOG_PATHNobeside EXPENSE_DB_PATHDedicated audit file for unauthorized access attempts
LOG_LEVELNoINFOPython logging level for the bot's stdout logs. An invalid value falls back to INFO with a warning

User authorization

Only Telegram user IDs listed in the whitelist can interact with the bot. Everyone else is silently ignored and recorded in the audit log.

# authorized-users.json
{
  "authorized_users": ["123456789"]
}

Values must be numeric strings. Find your own ID by messaging @userinfobot.

Startup failure behavior

SituationBehavior
Path not set, file missing, or file unreadableBot starts with no authorized users and logs a warning
Valid JSON, invalid schemaBot starts with no authorized users and logs a warning
Malformed JSONStartup fails
Audit log not writableStartup fails

Audit log

Each unauthorized attempt appends one line:

2026-07-19T12:00:00Z user_id=987654321

Data & privacy

  • Storage — a single SQLite file. Amounts are stored as exact decimal strings (no floating-point drift).
  • User isolation — every read and write is scoped to the sender's Telegram user ID. A user can only see, report, and delete their own expenses.
  • Multi-currency — expenses keep their original ISO 4217 currency. No conversion to a base currency is performed.
  • Deletion — deleting an expense marks it as deleted (logical deletion) so records are auditable and IDs stay stable.

Example: run from a source checkout

cp .env.example .env
uv sync
uv run pre-commit install
# migrations run through the project's Liquibase wrapper
export PATH="$PWD/scripts:$PATH"
# fill in .env, create authorized-users.json, then:
uv run expense-bot

The bot migrates the database before it opens it (ADR 0013). The wrapper on your PATH runs the official Liquibase Docker image, so Docker is required even when you run the bot from a source checkout — or you can put your own liquibase CLI on the PATH instead.