Operations guide

Keep credentials private and failures understandable.

Generated bots are small enough to inspect. Review config.json, bot.py, dependencies, deployment files, and every knowledge source before running them.

Credential rules

Copy .env.example to .env; never put a real key in the example file.
Do not commit .env. The generated .gitignore excludes it.
Set a long random BOT_ACCESS_TOKEN before binding web chat beyond loopback; the runtime fails closed without it.
Use cloud secret stores rather than manifest literals.
Rotate provider, Discord, Telegram, web-access, or AMT tokens after accidental exposure.
Give platform bots only the permissions they need.

Knowledge and prompt injection

Local knowledge is inserted into model context and may contain misleading instructions. Use only trusted text, Markdown, CSV, and JSON files. URL knowledge is disabled until ALLOW_KNOWLEDGE_URLS=true; enabling it causes the user’s machine to fetch the configured URLs.

Knowledge is data, not authority.

Do not let instructions found in documents or web pages override the bot’s system policy, reveal credentials, or authorize external actions.

Memory

SQLite memory is local to memory.db or BOT_DATA_DIR. It may contain conversation content. Back it up only if needed, restrict filesystem access, and delete it according to your privacy policy. Selecting “no persistent memory” prevents new database writes but does not erase an old database.

Common problems

Symptom	Check
401/403 from model provider	Correct key variable, account access, model name, and base URL.
Connection refused for Ollama/LM Studio	Model server is running and `LLM_BASE_URL` uses a reachable host/port. Between private machines, prefer the model host’s Tailscale IP.
Blank answer from a reasoning model	Increase max output tokens to at least 500–1,200; a tiny limit may be consumed before visible text.
Discord bot is online but silent	Message Content Intent, channel permissions, and token.
Telegram does not reply	BotFather token, polling process, group privacy, and another process consuming updates.
Web chat works locally but not in Docker	`HOST=0.0.0.0`, port 8000 mapping, and host firewall.
AMT says tool is not enabled	Tool is present in `config.json → tools → amt`; regenerate or edit through Builder.
AMT file call fails	Use `file_path`, supported type, readable path, and file below 25 MB.
Rate limit reached	Wait one minute or adjust the bounded Advanced-mode requests-per-minute setting.

Clean diagnostic commands

python --version
python -m py_compile bot.py
python -m pip install -r requirements.txt
python bot.py --check
python -c "import json; print(json.load(open('config.json'))['provider'])"
docker compose config
docker compose logs --tail=100 bot

Redact keys, tokens, private prompts, file contents, user messages, and absolute personal paths before sharing diagnostics.

Updating a bot

Keep a private backup of .env, knowledge, and memory.
Import the old config.json into Bot Builder.
Review the normalized preview and download a fresh runtime.
Move only the private runtime data you still need.
Test locally before replacing a deployed instance.

← AMT tools Build a bot →