Skip to main content
Getting SAFIA running takes three commands. The installer handles Git, Python 3.12, uv, and all dependencies automatically, then registers a safia CLI so you can manage the bot from anywhere in your terminal. No external cache server is required — SAFIA uses an in-memory cache backed by SQLite. Follow the steps below to go from zero to a live Telegram bot.

​
Prerequisites

Before you start, make sure you have:
  • A Telegram bot token — create one for free by messaging @BotFather on Telegram and running /newbot
  • An LLM API key from Lunos, Groq, OpenAI, or any OpenAI-compatible provider
  • A machine running Linux, macOS, or Windows with internet access
SAFIA does not require any external cache server. Chat history, rate-limit counters, and market data caches live in an in-memory cache that is persisted to SQLite (CACHE_DB_PATH), so cached state survives bot restarts.

​
Installation & Setup

1

Install SAFIA

Run the one-line installer for your operating system. It sets up all dependencies and registers the safia CLI command.
The installer automatically handles Git, uv, Python 3.12, and all Python dependencies. No Docker or external cache server required.
Once complete, the safia command is available in any new terminal session.
2

Run the Setup Wizard

The interactive setup wizard creates your .env configuration file. It walks you through each required setting one prompt at a time.
You will be asked for:
  • Your Telegram bot token
  • Your LLM provider (Lunos, Groq, OpenAI, or custom)
  • Your LLM API key
  • Database URL and persistent cache file path (defaults are pre-filled and work out of the box)
  • Optional: a Groq API key for voice transcription (Whisper) if your LLM provider is not Groq
  • Optional: a Firecrawl API key for web search and article fetching
Accept the default values for DATABASE_URL and CACHE_DB_PATH unless you have a specific reason to change them. SQLite (for both your data and the persisted cache) is the recommended starting point.
3

Start the Bot

Launch the bot and admin dashboard as background daemons. On Linux this uses systemd, on macOS launchd, and on Windows Scheduled Tasks — so SAFIA restarts automatically after a reboot.
Verify everything is running:
To watch recent logs:
4

Send Your First Message on Telegram

Open Telegram and find the bot you created with BotFather. Send the /start command to begin a new session, or send /help to see an overview of what SAFIA can do.From here, just chat naturally. For example:
  • “I spent 45000 on lunch today”
  • “Show me my expenses this week”
  • “What’s the current gold price?”
SAFIA responds in whatever language you write in. The daily message limit is 1000 messages per user by default — you can raise this with the DAILY_MESSAGE_LIMIT variable in your .env.
5

Access the Admin Dashboard (Optional)

The admin dashboard provides usage metrics, a user registry, and tools for uploading knowledge base documents.Open your browser and navigate to:
The dashboard requires HTTP Basic Auth. Set ADMIN_USERNAME and ADMIN_PASSWORD in your .env file (or run safia config to edit them) before accessing the dashboard for the first time. If these are not set, the dashboard is accessible without a password — protect it before exposing the port.

​
CLI Reference

The safia CLI manages every aspect of the bot’s lifecycle.

​
Next Steps

Configuration

Customise your LLM provider, database backend, rate limits, and more.

Admin Dashboard

Upload knowledge base documents and monitor user activity.