alice.The music bot
field guide
Complete setup / Local Linux

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.

Local Linux · dependencies
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 nano

2. Get the Alice bot source

Download the official Alice bot source ↗. Use this repository, not the documentation website ZIP.

Local Linux · download Alice
git clone https://github.com/thanosbots/Alice.git
cd Alice

If 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

Local Linux · project setup
bash setup.sh

Wait 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

  1. Open my.telegram.org ↗ and sign in with your Telegram phone number.
  2. Open API development tools, complete the application form, and save the api_id and api_hash.
  3. Use your own application values in the session generator and in Alice’s configuration.

Create the bot

  1. Open the verified @BotFather ↗ account on Telegram.
  2. Send /newbot. Choose a display name and an available username ending in bot.
  3. Save the returned token for BOT_TOKEN. Open the new bot and press Start.

Create a MongoDB database

  1. Sign in to MongoDB Atlas ↗, create a project, and create a database deployment. Select the plan and region appropriate for you.
  2. 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.
  3. 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.
  4. Open the deployment’s Connect → Drivers flow. Select Python and copy the connection URI.
  5. 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 ↗

  1. Open @elite_session_maker_bot and press Start.
  2. Select Pyrogram v2 for Alice.
  3. Follow the bot’s prompts using the Telegram user account you want to use as the assistant.
  4. Copy the generated Pyrogram session string.
  5. In the next step, paste it after STRING_SESSION= in Config.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

Local Linux · configuration
nano Config.env

Replace the example values with your own. The first six values below are placeholders, not credentials. Keep numeric IDs as plain numbers.

Config.env
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.

  1. Press Ctrl + O to save.
  2. Press Enter to confirm Config.env.
  3. Press Ctrl + X to return to the terminal.
Local Linux · keep configuration private
chmod 600 Config.env

Do 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.

Local Linux · create tmux session
tmux new -s alice

Inside that session, start Alice:

Local Linux · inside tmux
bash start.sh

In 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.

Local Linux · confirm the session
tmux ls

You should see a session named alice. You can now close the terminal or disconnect SSH.

8. Play your first song

  1. Add your bot to a Telegram group and give it permissions to manage voice chats and invite the assistant.
  2. Add the assistant user to the group, or allow the bot to invite it. Make sure the assistant can speak.
  3. Start a group voice chat and join it.
  4. Send /play song name artist. For choices, use /search song name.
  5. Try /queue to see the lineup. Use an admin account for /pause, /resume and /skip.
  6. From the owner account, privately send /help to 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.

Local Linux · reconnect
tmux attach -t alice

Stop: 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:

Local Linux · restart inside tmux
nano Config.env
# Save: Ctrl+O, Enter. Exit: Ctrl+X.
bash start.sh

On 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:

Local Linux · inspect output
tmux capture-pane -p -S -100 -t alice

Finish 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 alice exists, attach to it. If the bot has returned to a shell prompt, read the error, fix the cause, and run bash start.sh again.
  • If it does not exist, return to your project folder, create the session and start Alice:
Local Linux · after reboot
cd Alice
tmux new -s alice
# Run this inside the new session:
bash start.sh

Run 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 alice reopens 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
Search the field guide · ↓ to select · Enter to open · Esc to close