Skip to main content
This page answers the questions that come up most often when setting up and using SAFIA. Topics range from initial configuration and LLM provider choices to privacy, multi-user support, and data management. If you don’t find your answer here, run safia logs to inspect runtime errors, or consult the Troubleshooting page for step-by-step diagnostics.

​
Usage & Limits

By default, each Telegram user can send 25 messages per day. The counter resets at UTC midnight and applies equally to text messages, voice messages, and photo scans — each counts as one message.If you host SAFIA yourself and need a higher limit, open your .env file and set:
DAILY_MESSAGE_LIMIT=50
Then restart SAFIA:
safia restart
You can set the limit as high as you like — there is no enforced maximum on the server side.
Yes. SAFIA detects the language of your message and responds in the same language. While the bot’s personality and default financial context (e.g. IDR prices, Indonesian markets) are tuned for Indonesian users, you can converse naturally in English and receive English replies.
SAFIA’s primary currency is Indonesian Rupiah (IDR). It also supports USD → IDR conversion using live exchange rates refreshed every hour. Gold and silver prices are returned in IDR by default.If you need broader multi-currency support, you can ask SAFIA about exchange rates for other currency pairs — it will attempt to retrieve them — but IDR is the core reference currency for expense tracking and portfolio calculations.

​
Setup & Requirements

No. SAFIA is explicitly local-first and Docker-free. The installer handles Python, uv, dependencies, and Redis in a single script:
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/superXdev/SAFIA/main/install.sh | bash

# Windows (PowerShell)
iex (irm https://raw.githubusercontent.com/superXdev/SAFIA/main/install.ps1)
The bot and admin dashboard run as native OS daemons (systemd on Linux, launchd on macOS, Scheduled Tasks on Windows). No container runtime is needed at any point.
On Windows only, Redis must be installed separately before running the installer. The recommended options are Memurai, WSL, or a standalone Docker container just for Redis: docker run -d -p 6379:6379 --name safia-redis redis:7-alpine.
You create a bot and receive a token through @BotFather on Telegram:
1

Open BotFather

Search for @BotFather in Telegram and start a conversation.
2

Create a new bot

Send /newbot and follow the prompts — you’ll choose a display name and a username (must end in bot).
3

Copy your token

BotFather will send a token that looks like 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ. Copy it into the TELEGRAM_BOT_TOKEN field when you run safia setup.
Keep your token private — anyone who has it can control your bot.
SAFIA supports four provider options, set via LLM_PROVIDER in your .env:
ProviderLLM_PROVIDER valueNotes
LunoslunosDefault. Routes to https://api.lunosrouter.com/v1
GroqgroqRoutes to https://api.groq.com/openai/v1
OpenAIopenaiRoutes to https://api.openai.com/v1
CustomcustomAny OpenAI-compatible API; set LLM_BASE_URL to your endpoint
Set the corresponding key in LLM_API_KEY. For custom providers, also set LLM_BASE_URL and choose an appropriate LLM_MODEL name.
Voice transcription always requires a separate GROQ_API_KEY, regardless of which provider you choose for chat. SAFIA uses Whisper via the Groq API for speech-to-text and there is currently no alternative backend for this feature.
Lunos is the default LLM provider for SAFIA, accessed at https://api.lunosrouter.com/v1. It is an LLM routing service that exposes an OpenAI-compatible API, allowing SAFIA to use a range of models without you needing accounts at multiple providers.When you run safia setup and don’t specify a different provider, SAFIA configures itself to use Lunos automatically. You can switch to Groq, OpenAI, or any custom OpenAI-compatible provider at any time by updating LLM_PROVIDER and LLM_API_KEY in your .env and restarting.

​
Privacy & Data

Yes. SAFIA is local-first — your data never leaves your machine unless you explicitly configure a remote service. Here’s where each component runs:
ComponentLocation
Expense & investment recordsLocal SQLite (or your own PostgreSQL)
Chat historyLocal Redis
Vector embeddings (knowledge base)Local Qdrant on-disk storage
Embedding modelLocal ONNX file, runs on CPU
The only data that travels to external services is the content of your chat messages, which is sent to your chosen LLM API (Lunos, Groq, OpenAI, or custom) to generate responses — the same as any AI chat assistant. Market data (gold prices, crypto rates, etc.) is fetched from public APIs.
If you want to minimise data sent externally, you can self-host a compatible LLM and point LLM_BASE_URL at your local server using the custom provider option.
Yes. SAFIA maintains per-user records keyed to each person’s Telegram user ID. Expenses, debts, investments, reminders, and chat history are all stored separately for each user — one SAFIA instance can serve a family or small team without mixing data between accounts.By default, any Telegram user who messages the bot can use it. If you want to restrict access, enable the allowlist in the admin dashboard at http://127.0.0.1:5454 and add each approved user ID.
The daily message limit (default 25) applies per user, not per instance. Each user has their own independent counter.
SAFIA’s database is a single SQLite file. Back it up by copying:
data/safia.db
For example:
cp data/safia.db ~/backups/safia-$(date +%Y%m%d).db
If you’ve switched to PostgreSQL, use pg_dump to back up that database instead. The local Qdrant vector index is stored at data/qdrant/ — include this directory if you also want to preserve your knowledge base embeddings.
Stop SAFIA before copying the SQLite file to avoid backing up a partially written state: safia stop && cp data/safia.db ~/backups/safia.db && safia start.
Yes. SQLite is the default (zero configuration required), but SAFIA fully supports PostgreSQL for production or multi-user deployments that need better concurrency.Set DATABASE_URL in your .env to your PostgreSQL connection string:
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/safia
Then restart SAFIA:
safia restart
SAFIA creates the required tables automatically on first startup. Make sure the target database already exists before starting.

​
Features & Capabilities

The admin dashboard’s knowledge base accepts three file types:
  • PDF (.pdf) — financial statements, policy documents, reports
  • Plain text (.txt) — notes, custom rules, raw data exports
  • Word documents (.docx) — formatted documents from Microsoft Word or compatible editors
Files are chunked into overlapping segments (default: 450 words per chunk, 70-word overlap), embedded using the local ONNX model, and stored in the on-disk Qdrant vector index. The maximum upload size is 200 MB per file by default, configurable via KB_MAX_UPLOAD_MB in .env.Once uploaded, SAFIA automatically retrieves relevant passages from the knowledge base to ground its responses — no extra commands needed.
Run the built-in update command:
safia update
This pulls the latest code from GitHub, updates Python dependencies, and restarts the daemons automatically. Your .env configuration and data files are preserved.
If the update introduces changes to the database schema, SAFIA runs any required migrations on the next startup. Always back up data/safia.db before a major update.
Yes. Send a voice message to the bot and SAFIA transcribes it using Whisper via the Groq API, then processes the transcribed text as a normal message. The transcription step requires a valid GROQ_API_KEY in your .env — this key is free to obtain from console.groq.com and is required even if you use a different provider for chat.Voice messages count toward your daily message limit (25 by default) the same as text messages.
Yes. Send a clear photo of a receipt, payslip, or invoice and SAFIA will extract the content using your configured vision model, identify the final amount (net salary, total after discounts, etc.), and prompt you to record the transaction.Photo scanning requires a valid LLM_API_KEY. The vision model defaults to mistralai/mistral-small-3.2-24b-instruct and can be changed via the VISION_MODEL setting in .env.For best results:
  • Make sure the document is well-lit and fully in frame.
  • Avoid steep angles or heavy shadows.
  • Use the highest camera resolution your device supports.