Skip to main content
Getting SAFIA running takes three commands. The installer handles Git, Python 3.12, uv, Redis, and all dependencies automatically, then registers a safia CLI so you can manage the bot from anywhere in your terminal. 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
On Windows, Redis is not bundled with the installer. You must install it separately before running safia setup. Options include Memurai, Redis via WSL, or Docker: docker run -d -p 6379:6379 --name safia-redis redis:7-alpine.

​
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.
curl -fsSL https://raw.githubusercontent.com/superXdev/SAFIA/main/install.sh | bash
The installer automatically handles Git, uv, Python 3.12, Redis, and all Python dependencies. No Docker 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.
safia setup
You will be asked for:
  • Your Telegram bot token
  • Your LLM provider (Lunos, Groq, OpenAI, or custom)
  • Your LLM API key
  • Database and Redis URLs (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 REDIS_URL unless you have a specific reason to change them. SQLite and local Redis are 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.
safia start
Verify everything is running:
safia status
To watch recent logs:
safia 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 /bantuan 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 25 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:
http://127.0.0.1:5454
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.
CommandDescription
safia setupRun the interactive setup wizard
safia configView and edit configuration interactively
safia startStart bot and admin dashboard daemons
safia stopStop both daemons
safia restartRestart both daemons
safia statusShow current daemon status
safia logs [N]Show recent logs (default: last 30 lines)
safia updatePull latest changes, update deps, and restart
safia testRun the test suite
safia uninstallRemove SAFIA completely

​
Next Steps

Configuration

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

Admin Dashboard

Upload knowledge base documents and monitor user activity.