Configuration¶

This page covers where Agent Zero Core keeps its settings and how to connect a private Telegram bot.

Where configuration lives¶

Host path	Inside the container	Contents
`/var/lib/agent-zero-core/usr`	`/a0/usr`	Settings, model configuration, projects, plugin state, uploads and the working folder

The folder is owned by UID/GID 10000:10000, the user the container runs as, with mode 0700. Keep that ownership and mode.

The container is managed by agent-zero-core.service. It runs with a read-only root file system, a 2 CPU and 2 GiB memory limit, and publishes only 127.0.0.1:5080. Only /var/lib/agent-zero-core/usr is writable and kept across restarts.

Models¶

Configure providers, models and keys in Agent Zero's settings. To rotate a provider key, update it there.

Plugins¶

The plugins that are not part of Core stay off and cannot be turned on: memory embeddings, browser, desktop, office, document query, text-to-speech, speech-to-text, email and WhatsApp. A2A is not available.

Telegram¶

Telegram is optional. Finish the test task in the UI first.

You can set up Telegram with the installed helper, which is the tested path. It requires an explicit allowlist, turns off group chats and uses polling.

If you use the native Telegram wizard instead

Set the allowed users explicitly, choose polling and turn groups off. The wizard's default empty allowlist lets anyone who finds the bot talk to your agent.

1. Prepare a dedicated bot¶

Create a new bot with BotFather in your own Telegram account. Use a bot that nothing else polls.
Note the bot token and your private chat ID.

Treat the bot token as a secret. Keep it out of shell commands, URLs and logs.

2. Create the private file¶

Open the file in an editor as root:

sudoedit /root/agent-zero-telegram.private.json

Paste this template and fill it in:

{
  "token": "",
  "allowed_private_chat_ids": [],
  "bot_name": "private-agent-zero"
}

Field	Value
`token`	Your bot token
`allowed_private_chat_ids`	Private chat IDs allowed to talk to the agent, as strings of digits. At least one.
`bot_name`	A short name: lowercase letters, digits and hyphens, starting with a letter

No other fields are allowed. Make the file root-only:

sudo chown root:root /root/agent-zero-telegram.private.json
sudo chmod 0600 /root/agent-zero-telegram.private.json

3. Check and enable¶

Validate the file. This makes no connection to Telegram:

sudo python3 /opt/sushi/bin/agent-zero-core-configure-telegram.py \
  --private-config /root/agent-zero-telegram.private.json --check-only

Then configure the plugin and start polling:

sudo python3 /opt/sushi/bin/agent-zero-core-configure-telegram.py \
  --private-config /root/agent-zero-telegram.private.json --enable

The token is passed to the container over standard input and is never printed. Without --enable, the helper saves the configuration but leaves polling off.

Change or stop the bot¶

Each instance supports one bot. The helper refuses to replace a bot with a different bot_name; use a separate instance for another bot.

To stop polling, run the helper again without --enable.
To change the token or allowlist, stop any other poller for the bot, edit the private file and run the helper again with --enable.

When you are done, delete any temporary copies of the private file.