Levix is a personal WhatsApp bot with a growing command catalog, group moderation, scheduled
messages, an AI agent, media tools, and a web control panel. You run it on your
own computer or server, keep its database and session files yourself, and can
change almost everything while it is running.
There is no paid tier, hosted account, external database, or configuration file
to maintain. Levix is released under the MIT License.
[!WARNING]
Levix uses Baileys, an unofficial
WhatsApp Web client, and is not affiliated with or endorsed by WhatsApp or
Meta. Unofficial automation can lead to temporary restrictions or an account
ban. Do not use Levix for spam or unsolicited bulk messaging. If an outage or
account restriction is unacceptable, use the official WhatsApp Business
Platform instead.
Quick start
Linux server
The public installer installs the latest stable release and configures Levix as
a service:
curl -fsSL https://levix.leviro.net/install.sh | bash
You can read the installer before running it.
npm
Requires Node.js 24 or newer:
npm install -g levix-bot
levix
Docker
git clone https://github.com/Abdodiab2005/levix
cd levix
docker compose up -d
docker compose logs levix
Android phone (No server required)
Run Levix directly on an Android device (Android 10+, ARM64 or ARMv7) as a self-contained background companion:
- Download
levix-android-arm64.apk (64-bit phones) or levix-android-armv7.apk (32-bit phones) from Releases.
- Install the APK and tap Start Assistant — the big circle on the home screen.
- Tap Connect WhatsApp to set your panel password and link WhatsApp via an 8-character pairing code.
See ANDROID.md for full instructions, OEM battery optimizations (Xiaomi, Samsung, OnePlus), and offline handling.
Standalone Linux, macOS ARM64, and Windows binaries are available from the
latest GitHub release.
When Levix starts:
- Open the panel URL printed in the terminal.
- Choose a panel password. A remote first-time setup also asks for the printed
setup code.
- Open Connection, press Start session, and scan the QR from WhatsApp.
- Send
!ping in a chat.
A successfully linked WhatsApp session resumes automatically after a process,
Docker, or systemd restart. See SETUP.md for domains, reverse
proxies, headless mode, backups, and troubleshooting.
What you get
| Area | What Levix provides |
|---|
| Commands | Utilities, notes, reminders, polls, media, speech, weather, prayer times, and more — configurable from the panel |
| Translation | !translate between Arabic and English, or into a language you name — with an AI engine (your active AI provider, with its own editable prompt) or Google's translation engine, plus summary, tone, explain, and detect options |
| Group moderation | Welcome messages, anti-link, anti-spam, media rules, and forbidden words in one linked pipeline with a shared warning counter per member — at the limit the group removes the member automatically or flags them for admin review, guided by a per-group policy (Relaxed / Standard / Strict presets, warning limit, per-feature actions, warning expiry); warnings, roles, rules, and notes too |
| AI agent | Pick Google Gemini, OpenAI / any OpenAI-compatible server, or Anthropic from the panel; each provider has its own endpoint, API key, and model, with tools for web search, page reading, memory, and role management |
| Scheduling | One-off, daily, and weekly messages with durable jobs, delivery status, and manual retry |
| Control panel | Live connection state, command settings, roles, permissions, keys, memory, schedules, and logs |
| Media | Text, images, video, audio, QR codes, text-to-speech, and speech-to-text |
| Stickers | Turn a photo, GIF, or short video into a sticker, and keep a personal library and packs from chat or the panel |
| Deployment | Android APK, npm, Docker, systemd installer, standalone binaries, headless mode, and safe domain setup |
| Storage | One SQLite database and one data directory for settings, sessions, memory, and logs |
Every command can be enabled, disabled, renamed, and assigned permissions from
the panel without restarting the bot.
AI that can act
The !gemini command is an agent rather than a plain chat box. It can run
several tool rounds, search the web, read a page, save long-term memories, and
manage bot roles. It narrates progress by editing one WhatsApp message and lists
sources when it uses web search.
AI answers are formatted for WhatsApp automatically: **bold** becomes *bold*,
__italic__ becomes _italic_, and tables become named entries with labeled
bullet points. Headings, lists, checkboxes, strikethrough and links are converted;
code contents and URLs are preserved.
Replies follow the language and dialect you write in — Egyptian Arabic in,
Egyptian Arabic out.
Use !md (or !markdown) to convert text from any other AI or message, without
an AI key. Reply to that message with !md, or paste Markdown after the command,
including multiline tables and code. For example: !md **Bold** and __italic__.
Existing WhatsApp *bold* and _italic_ text keeps its formatting.
AI is optional. The rest of Levix works without an AI key.
Persistent schedules and memory
One-off and recurring schedules survive restarts and record their latest
delivery outcome. Long-term memory is stored as plain Markdown in
memory/global.md or per-chat files, so it remains readable and editable
outside the panel.
A connection you control
The panel can start, stop, reconnect, and unlink WhatsApp while showing the
actual state: idle, waiting for a scan, connected, reconnecting, or stopped.
Reconnect attempts continue inside the bot even when no browser is open.
An optional HTTP, HTTPS, or SOCKS5 proxy can route WhatsApp traffic, including
media, without changing how the panel or AI connects.
CLI
levix start Levix with the web panel
levix headless start Levix with no web UI or open port
levix where print the data directory
levix reset-password reset the panel password
levix domain [name] configure a domain safely (may need sudo)
A fresh panel install waits for you to start the first WhatsApp pairing.
levix headless has no button to press, so it starts the session itself and
prints the QR in the terminal when needed.
Data and configuration
Everything mutable lives in one data directory:
- npm installation:
~/.levix
- source checkout:
./data
- Docker: the
levix-data volume
Copying this directory is a full backup, including the SQLite database, WhatsApp
session, memory, and logs.
The database is the source of truth. The prefix, permissions, API keys, server
settings, and feature options are stored in bot_settings and read at use
time. There is no .env or application configuration file to keep in sync.
Secrets are generated rather than shipped with defaults. The panel password is
stored as an scrypt hash, and the session-signing key is generated on first
start.
Architecture
- Node.js 24+ with ES modules and CommonJS where needed.
- Baileys v7 for the WhatsApp protocol engine, LID support, and phone pairing codes.
node:sqlite for a zero-dependency, single-file datastore.- React + Vite Control Panel (
frontend/) with TypeScript, native RTL Arabic / English internationalization, Lucide icons, responsive drawer, modal dialogs, and real-time Socket.IO synchronization.
- Express + EJS Gateways for lightweight setup, login, and pairing QR gateway screens.
- Pluggable AI providers — Google Gemini, OpenAI / any OpenAI-compatible endpoint, or
Anthropic — each with its own endpoint, API key, and model in the control panel, no env file.
- Biome for fast formatting and linting across the codebase.
- GitHub Actions validation for tests, npm packaging, Docker persistence,
Android APK packaging, and standalone executables on Linux, macOS, and Windows.
AGENTS.md documents the module layout, message flow, storage API,
and architectural constraints. PACKAGING.md covers npm, Docker,
systemd, installers, and single-executable releases.
Development
git clone https://github.com/Abdodiab2005/levix
cd levix
npm ci
cd frontend && npm ci && cd ..
npm run build # compiles the React frontend to public/dashboard
npm run lint # runs Biome linter across the project
npm test # runs the full test suite
npm start # starts Levix
Read the contributor walkthrough for the fork-to-pull-request workflow, then check CONTRIBUTING.md for the official repository rules. Bug reports and focused pull requests are welcome.
For security issues, follow SECURITY.md and report them
privately rather than opening a public issue.
Sending feedback
Settings → Feedback in the control panel writes straight to the developer.
The bot forwards it server-side to levix.leviro.net/api/feedback, which
delivers it as a Telegram message; the same form is on the web at
levix.leviro.net/feedback. It carries your
message, the topic, an optional rating, an optional contact and one optional
file you attach (a screenshot or a log, up to 20 MB), plus the version and
platform — and nothing from WhatsApp. Nothing leaves until you press Send.
Prefer a public, trackable bug report with logs attached? Open an
issue instead.
License
Levix is free and open source under the MIT License.
Built by Abdelrhman Diab under
Leviro.
