SAFIA is configured through a .env file created during safia setup. You can re-open that file at any time using the interactive editor, or edit it directly with a text editor. All variables below correspond to entries in .env.
The sections below group every supported variable by function. Variables marked required must be set before SAFIA will start successfully.
Required
These five variables are the minimum needed to run the bot.
| Variable | Description |
|---|
TELEGRAM_BOT_TOKEN | Your bot’s token from @BotFather. |
LLM_PROVIDER | The LLM backend to use: lunos, groq, openai, or custom. Defaults to lunos. |
LLM_API_KEY | API key for the selected LLM provider. |
DATABASE_URL | SQLAlchemy connection string. Defaults to sqlite+aiosqlite:///data/safia.db. |
REDIS_URL | Redis connection string. Defaults to redis://localhost:6379/0. |
.env for getting started:
TELEGRAM_BOT_TOKEN=your-telegram-bot-token
LLM_PROVIDER=lunos
LLM_API_KEY=your-api-key
DATABASE_URL=sqlite+aiosqlite:///data/safia.db
REDIS_URL=redis://localhost:6379/0
Never commit your .env file to version control. It contains credentials that grant full access to your bot and LLM account.
LLM Settings
SAFIA supports four LLM providers out of the box. Each provider’s base URL is set automatically — you only need to supply LLM_PROVIDER and LLM_API_KEY.
| Variable | Default | Description |
|---|
LLM_PROVIDER | lunos | Provider name: lunos, groq, openai, or custom. |
LLM_API_KEY | — | API key for the selected provider. |
LLM_MODEL | openai/gpt-oss-120b | Model identifier passed to the provider API. |
LLM_BASE_URL | — | Base URL for a custom OpenAI-compatible provider. Required only when LLM_PROVIDER=custom. |
VISION_MODEL | mistralai/mistral-small-3.2-24b-instruct | Model used for receipt and document photo extraction. Uses the same provider and API key as the chat model. |
LLM_PROVIDER=lunos
LLM_API_KEY=your-lunos-api-key
LLM_MODEL=openai/gpt-oss-120b
https://api.lunosrouter.com/v1) is set automatically.LLM_PROVIDER=groq
LLM_API_KEY=your-groq-api-key
LLM_MODEL=llama-3.3-70b-versatile
LLM_PROVIDER=openai
LLM_API_KEY=your-openai-api-key
LLM_MODEL=gpt-4o
LLM_PROVIDER=custom
LLM_API_KEY=your-api-key
LLM_BASE_URL=https://your-provider.example.com/v1
LLM_MODEL=your-model-name
LLM_BASE_URL to any endpoint that implements the OpenAI Chat Completions API.Speech-to-text always uses Whisper via Groq, regardless of which LLM provider you select for chat. If you use a non-Groq LLM provider, set GROQ_API_KEY separately to enable voice message transcription.
Voice Transcription and Web Search
Two optional integrations expand what SAFIA can do:
| Variable | Default | Description |
|---|
GROQ_API_KEY | — | Groq API key for Whisper voice transcription. Required if your LLM_PROVIDER is not groq. |
FIRECRAWL_API_KEY | — | API key from firecrawl.dev for web search and article fetching. Leave empty to disable web search. |
# Optional: enable voice messages when using a non-Groq LLM provider
GROQ_API_KEY=your-groq-api-key
# Optional: enable web search and article fetching
FIRECRAWL_API_KEY=your-firecrawl-api-key
Database & Cache
SAFIA stores all financial data in a relational database and uses Redis for chat history and rate limiting.
| Variable | Default | Description |
|---|
DATABASE_URL | sqlite+aiosqlite:///data/safia.db | SQLAlchemy async connection string. SQLite is zero-config; use a PostgreSQL URL for production deployments. |
REDIS_URL | redis://localhost:6379/0 | Redis connection string used for chat history, price caches, and per-user rate limiting. |
data/safia.db.
PostgreSQL — swap DATABASE_URL with an asyncpg connection string:
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/safia
SQLite is the recommended choice for personal use. Switch to PostgreSQL only if you plan to run SAFIA for multiple users concurrently or need point-in-time backups.
Admin Dashboard
The admin dashboard runs at http://127.0.0.1:5454 and provides usage metrics, a user registry, and knowledge base management. Protect it with HTTP Basic Auth before using it.
| Variable | Default | Description |
|---|
ADMIN_USERNAME | (empty) | Username for HTTP Basic Auth on the dashboard. |
ADMIN_PASSWORD | (empty) | Password for HTTP Basic Auth on the dashboard. |
FLASK_SECRET_KEY | (empty) | Secret key used by Flask for session signing. Set this to a long random string. |
ADMIN_USERNAME=admin
ADMIN_PASSWORD=a-strong-password-here
FLASK_SECRET_KEY=replace-with-a-random-secret-string
If ADMIN_USERNAME and ADMIN_PASSWORD are left empty, the dashboard is accessible without authentication. Always set these before exposing port 5454 beyond localhost.
Knowledge Base
The knowledge base (RAG) lets you upload documents that SAFIA uses to ground its responses. Embeddings and vector storage run locally by default.
| Variable | Default | Description |
|---|
QDRANT_PATH | data/qdrant | On-disk path for Qdrant vector storage. Used when no QDRANT_URL is set. |
QDRANT_URL | (empty) | URL of a remote Qdrant server. Overrides QDRANT_PATH when set. |
QDRANT_API_KEY | (empty) | API key for an authenticated remote Qdrant instance. |
KB_MAX_UPLOAD_MB | 200 | Maximum file size (in MB) for knowledge base document uploads. |
KB_CHUNK_WORDS | 450 | Number of words per document chunk when ingesting files. |
KB_CHUNK_OVERLAP_WORDS | 70 | Word overlap between consecutive chunks to preserve context. |
EMBEDDING_LOCAL | true | Set to false to use a remote embedding API instead of local ONNX. |
EMBEDDING_LOCAL_MODEL | sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 | Local ONNX embedding model (~120 MB, downloads once). |
QDRANT_URL=http://127.0.0.1:6333
QDRANT_API_KEY=your-qdrant-api-key
EMBEDDING_LOCAL=false
EMBEDDING_BASE_URL=https://openrouter.ai/api/v1
EMBEDDING_API_KEY=your-key
EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_VECTOR_SIZE=1536
The local embedding model downloads automatically on first use and runs on CPU via ONNX Runtime. No GPU is required. Switching to remote embeddings is only necessary if your machine has very limited disk space or you want to use a higher-dimensional model.
Reminders
SAFIA can send scheduled reminders for price alerts, news digests, and portfolio summaries.
| Variable | Default | Description |
|---|
REMINDER_ENABLED | true | Set to false to disable all scheduled reminders globally. |
REMINDER_MAX_PER_USER | 10 | Maximum number of active reminders a single user can have at one time. |
REMINDER_MAX_SENDS_PER_DAY | 15 | Maximum reminder messages sent to a user per day. |
REMINDER_TICK_SECONDS | 30 | How often (in seconds) the reminder scheduler checks for due reminders. |
REMINDER_ENABLED=true
REMINDER_MAX_PER_USER=10
REMINDER_MAX_SENDS_PER_DAY=15
Rate Limiting
SAFIA enforces a daily message limit per user to manage LLM API costs.
| Variable | Default | Description |
|---|
DAILY_MESSAGE_LIMIT | 25 | Maximum number of bot messages a single user can send per day. Resets at midnight. |
Increase DAILY_MESSAGE_LIMIT if you are the sole user of your SAFIA instance and want unrestricted access. Be mindful of your LLM provider’s rate limits and billing when raising this value.