◆ Agent Media Tools

Installation runbook

From ZIP to a verified first reply.

Set up the bot locally before connecting Discord, Telegram, a public domain, or a cloud bill. This procedure keeps credentials out of the project files and catches provider problems before deployment.

1. Check the prerequisites

# Linux/macOS
python3 --version
pwd
ls

# Windows PowerShell
py --version
Get-Location
Get-ChildItem

You should see bot.py, config.json, .env.example, requirements.txt, and the launch files. If Python is missing, install it from your operating system’s trusted package source or python.org. On Windows, enable the installer option that makes Python available from the command line.

2. Review before running

Open these files in a text editor:

FileWhat to confirm
config.jsonBot name, platform, provider, exact model ID, memory limit, knowledge URLs, and enabled AMT tools.
.env.exampleThe variables required for your provider and platform. It contains no secret values.
requirements.txtPinned Python packages. Web bots include Flask and Waitress; chat-platform bots include only their selected adapter.
knowledge/Only documents you trust and intend to send to the selected model provider.

3. Create the private environment file

# Linux/macOS
cp .env.example .env
chmod 600 .env

# Windows PowerShell
Copy-Item .env.example .env

Edit .env and fill only the variables you use. Do not surround ordinary values with smart quotes, add spaces around =, paste credentials into config.json, or commit .env.

# Local LM Studio example
LLM_BASE_URL=http://127.0.0.1:1234/v1
LMSTUDIO_API_KEY=

# Hosted provider example—use your real key privately
OPENAI_API_KEY=replace_locally

# Required only for Discord/Telegram
DISCORD_BOT_TOKEN=
TELEGRAM_BOT_TOKEN=

# Required when web chat binds beyond this computer
BOT_ACCESS_TOKEN=replace_with_a_long_random_value
HOST=127.0.0.1
PORT=8000
Choose one provider path.

You do not need to fill every key. The provider selected in config.json determines which credential is read. LLM_BASE_URL can override the generated endpoint without editing the configuration.

4. Install into an isolated environment

The included launchers automate this, but the manual commands make each step visible:

# Linux/macOS
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

# Windows PowerShell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

If PowerShell blocks activation, you may run .\.venv\Scripts\python.exe bot.py directly instead of changing the machine-wide execution policy. Re-run dependency installation whenever requirements.txt changes.

5. Run the no-prompt diagnostic

# With the virtual environment active
python bot.py --check

The check contacts the provider’s model-list endpoint, confirms the selected model when the provider returns a list, verifies required Discord or Telegram tokens, and rejects an exposed web bind without BOT_ACCESS_TOKEN. It does not send a model prompt. A successful result ends with:

OK: provider reachable; model and required platform settings are configured

If it reports that the model is not listed, copy the exact model identifier from the provider or local server. For LM Studio and compatible servers, inspect http://127.0.0.1:1234/v1/models or the equivalent private endpoint without exposing it publicly.

6. Start and test locally

PlatformStartFirst verification
Terminalpython bot.pySend a short factual prompt, then /quit.
Webpython bot.pyOpen http://127.0.0.1:8000 and check /healthz.
Discordpython bot.pyMention or message it in a private test channel.
Telegrampython bot.pySend it a direct message before adding it to a group.
# Web health check from another terminal
curl --fail http://127.0.0.1:8000/healthz

# Expected shape
{"name":"Your Bot","ok":true,"templateVersion":1}

7. Test restart and persistence

  1. Send two messages that establish harmless context.
  2. Stop with Ctrl+C.
  3. Start the bot again and verify the selected memory behavior.
  4. Confirm memory.db is created only when SQLite memory is enabled.
  5. Back up or delete that database according to your privacy requirements.

memory.db contains conversation content. “No persistent memory” stops new writes; it does not erase an existing database.

8. Optional Docker rehearsal

docker version
docker compose config
docker compose build
docker compose up -d
docker compose ps
docker compose logs --tail=100 bot

For web bots, open http://127.0.0.1:8000/healthz. Compose sets HOST=0.0.0.0 inside the container, so configure BOT_ACCESS_TOKEN first. The named bot-data volume retains SQLite memory across container replacement. docker compose down keeps that volume; docker compose down -v deletes it.

Ready-to-deploy gate