Alice on Local Linux.
Start with the system tools. Finish with a running bot in tmux. Follow these steps in order on the same machine.
1. Install Linux system tools
Open Terminal on your Ubuntu or Debian computer. Use your normal account with sudo access. Enter your computer’s password when sudo asks; the password is not displayed as you type.
sudo apt update
sudo apt install -y python3 python3-venv python3-pip python3-dev \
build-essential pkg-config git curl ca-certificates unzip ffmpeg tmux nano2. Get the Alice bot source
Download the official Alice bot source ↗. Use this repository, not the documentation website ZIP.
git clone https://github.com/thanosbots/Alice.git
cd AliceIf you already have an extracted Alice source folder, skip cloning and use cd "/absolute/path/to/Alice" instead. Keep using that same folder for the remaining commands. Do not copy an existing virtual environment from another operating system.
3. Install Alice’s Python packages
bash setup.shWait for Setup complete. Setup installs uv into a local bootstrap environment, prepares Python 3.11, and installs the pinned packages in .venv. It also creates Config.env when one does not exist. Do not use sudo for this command.
4. Collect Telegram & database credentials
Create your Telegram application
- Open my.telegram.org ↗ and sign in with your Telegram phone number.
- Open API development tools, complete the application form, and save the
api_idandapi_hash. - Use your own application values in the session generator and in Alice’s configuration.
Create the bot
- Open the verified @BotFather ↗ account on Telegram.
- Send
/newbot. Choose a display name and an available username ending inbot. - Save the returned token for
BOT_TOKEN. Open the new bot and press Start.
Create a MongoDB database
- Sign in to MongoDB Atlas ↗, create a project, and create a database deployment. Select the plan and region appropriate for you.
- Under Database Access, create an application database user with read/write access to the bot’s database. Save its username and password; these are separate from your Atlas login.
- Under Network Access, allow the bot host’s public IP address. On a VPS use its outbound public IP, not your laptop’s IP. On a home connection update the entry if your public IP changes.
- Open the deployment’s Connect → Drivers flow. Select Python and copy the connection URI.
- Replace the username/password placeholders, URL-encoding special characters as required. Put this full URI in
MONGO_URL.
These guides use hosted MongoDB, so a MongoDB server does not need to be installed on your bot machine. The Python client is installed by Alice’s setup script. See Atlas documentation ↗ for the current console steps.
5. Generate the assistant session
Use our dedicated Telegram session maker:
- Open @elite_session_maker_bot and press Start.
- Select Pyrogram v2 for Alice.
- Follow the bot’s prompts using the Telegram user account you want to use as the assistant.
- Copy the generated Pyrogram session string.
- In the next step, paste it after
STRING_SESSION=inConfig.env.
The session maker also offers Elite and Telethon formats. Alice uses the Pyrogram v2 option.
Keep the session string private. For an optional local generator and a way to read your numeric owner ID, see the assistant session guide.
6. Fill Config.env with nano
nano Config.envReplace the example values with your own. The first six values below are placeholders, not credentials. Keep numeric IDs as plain numbers.
API_ID=YOUR_NUMERIC_API_ID
API_HASH=YOUR_API_HASH
BOT_TOKEN=YOUR_BOT_TOKEN
STRING_SESSION=YOUR_EXPORTED_ASSISTANT_SESSION
MONGO_URL=YOUR_COMPLETE_MONGODB_URI
OWNER_ID=YOUR_NUMERIC_TELEGRAM_USER_ID
LOG_GROUP_ID=0
MUSIC_QUALITY=320
MAX_DOWNLOAD_MB=40
MAX_TRACK_MINUTES=30
MAX_QUEUE_SIZE=50
UPDATE_REPO=https://github.com/thanosbots/Alice.git
UPDATE_BRANCH=Use LOG_GROUP_ID=0 to start without a log chat. The bot includes its welcome, help and ping artwork. To enable a log chat later, set its numeric chat ID and make sure the bot can send messages there.
- Press Ctrl + O to save.
- Press Enter to confirm
Config.env. - Press Ctrl + X to return to the terminal.
chmod 600 Config.envDo not add this file or your sessions to Git. The full meaning of each setting is in the configuration reference.
7. Start Alice inside tmux
From the Alice project folder, create a named session. It opens a new terminal view in the same directory.
tmux new -s aliceInside that session, start Alice:
bash start.shIn your desktop Power settings, disable automatic suspend while hosting, and keep the computer powered and online.
Wait for LISTENING ROOM OPEN. If startup prints an error, correct it before detaching.
Detach: press Ctrl + B, release both keys, then press D. You return to the outer shell and Alice keeps running. This is different from Ctrl + C, which stops the bot.
tmux lsYou should see a session named alice. You can now close the terminal or disconnect SSH.
8. Play your first song
- Add your bot to a Telegram group and give it permissions to manage voice chats and invite the assistant.
- Add the assistant user to the group, or allow the bot to invite it. Make sure the assistant can speak.
- Start a group voice chat and join it.
- Send
/play song name artist. For choices, use/search song name. - Try
/queueto see the lineup. Use an admin account for/pause,/resumeand/skip. - From the owner account, privately send
/helpto your bot to check owner access.
9. Reconnect, stop & restart
Reconnect using the same operating-system user that created the tmux session. On the VPS, SSH back in first.
tmux attach -t aliceStop: inside the attached session, press Ctrl + C once and wait for the shell prompt. This ends the bot process, leaving the tmux shell available.
Edit and restart: after stopping the old process, run:
nano Config.env
# Save: Ctrl+O, Enter. Exit: Ctrl+X.
bash start.shOn Mac, use caffeinate -i bash start.sh if you want the idle-sleep protection. Detach again with Ctrl + B, then D. Start only one bot process per assistant session.
View recent terminal output: from outside the session, run:
tmux capture-pane -p -S -100 -t aliceFinish the session: attach, stop Alice with Ctrl + C, then type exit. tmux ls no longer lists that session.
After a reboot or an unexpected exit
tmux does not automatically recreate sessions after a reboot or restart crashed processes. Log in, check tmux ls, then:
- If
aliceexists, attach to it. If the bot has returned to a shell prompt, read the error, fix the cause, and runbash start.shagain. - If it does not exist, return to your project folder, create the session and start Alice:
cd Alice
tmux new -s alice
# Run this inside the new session:
bash start.shRun this from the directory where you originally cloned Alice. If you stored it elsewhere, use cd /path/to/Alice. Detach after startup succeeds.
Updating the bot
Privately send /update from the owner account. Alice shows its current version and checks the configured repository. If a newer release exists, choose Confirm update to install that exact release, or Cancel to keep the current version. The confirmation expires after ten minutes.
Installation prepares dependencies separately, saves a code backup and restarts the bot. Music stops at restart. Configuration and sessions are preserved. Keep using bash start.sh so later starts use the updated environment. Read-only hosts and containers should be redeployed.
10. If a step fails
- Duplicate session:
tmux attach -t alicereopens the existing one. - No sessions: check that you are logged in as the original OS user; otherwise create a new session after confirming the old bot isn’t running.
- Database connection fails: review the database user, URI and host IP in Atlas.
- Assistant cannot join: check group membership and call speaking permissions.
- Package install fails: check network access and the exact error. Do not launch Alice until setup completes.
More fixes are in Troubleshooting. Official references: tmux ↗, Telegram API credentials ↗ and MongoDB Atlas ↗.
KEEP GOINGExplore Alice commands