alice.The music bot
field guide
Complete setup / macOS

Alice on macOS.

Start with the system tools. Finish with a running bot in tmux. Follow these steps in order on the same machine.

1. Install Mac system tools

Open Applications → Utilities → Terminal. Use your normal macOS account. First install Apple’s command-line developer tools if missing:

macOS · developer tools
xcode-select -p || xcode-select --install

If an installer window opens, finish it before continuing. Then check Homebrew:

macOS · check Homebrew
command -v brew

If that prints no path, install Homebrew using its official installer:

macOS · install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the installer’s Next steps to add Homebrew to your shell profile. For the current terminal, this detects the standard Apple Silicon or Intel location:

macOS · enable Homebrew
if [ -x /opt/homebrew/bin/brew ]; then
  eval "$(/opt/homebrew/bin/brew shellenv)"
elif [ -x /usr/local/bin/brew ]; then
  eval "$(/usr/local/bin/brew shellenv)"
fi
brew --version

Install the tools Alice needs:

macOS · dependencies
brew update
brew install python@3.11 git ffmpeg tmux nano
export PATH="$(brew --prefix python@3.11)/libexec/bin:$PATH"

Use the Homebrew installation guide ↗ for its current macOS support requirements. Do not run brew install with sudo.

2. Get the Alice bot source

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

macOS · 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

macOS · 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

macOS · 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.
macOS · 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.

macOS · create tmux session
tmux new -s alice

Inside that session, start Alice:

macOS · inside tmux
bash start.sh

For a longer local session, use this instead of the previous launch command to prevent idle sleep while Alice runs:

macOS · awake while running
caffeinate -i bash start.sh

Keep your Mac powered, connected and its lid open. A sleeping or shut-down computer cannot keep the bot 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.

macOS · 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.

macOS · 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:

macOS · 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:

macOS · 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:
macOS · 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