Quick start

1. Prerequisites

• Telegram bot from @BotFather with topics in private chats enabled
• Shell access on the host (to approve pairing — you do not need to look up a user id first)
• At least one agent CLI on PATH: grok, claude, codex, or opencode

2. Download binaries

From GitHub Releases grab worker + host for your platform: linux-x64, linux-arm64, darwin-arm64, darwin-x64.

# example: v0.1.0 on Apple Silicon
curl -sL -o acpbot.tar.gz \
  "https://github.com/pmdroid/acpbot/releases/download/v0.1.0/acpbot-v0.1.0-darwin-arm64.tar.gz"
curl -sL -o acpbot-host.tar.gz \
  "https://github.com/pmdroid/acpbot/releases/download/v0.1.0/acpbot-host-v0.1.0-darwin-arm64.tar.gz"
tar -xzf acpbot.tar.gz && tar -xzf acpbot-host.tar.gz
chmod +x acpbot-v0.1.0-darwin-arm64 acpbot-host-v0.1.0-darwin-arm64

# optional — install on PATH
sudo mv acpbot-v0.1.0-darwin-arm64 /usr/local/bin/acpbot
sudo mv acpbot-host-v0.1.0-darwin-arm64 /usr/local/bin/acpbot-host

3. Run host + worker

acp-host is required. The worker exits at boot if the host socket is missing.

On first start the app creates ~/.config/acpbot/ and ~/.local/share/acpbot/ for you.

# guided TUI — config, API keys, optional background services
acpbot setup

# if you skip the daemon step:
acpbot-host    # terminal 1 — agents / schedules
acpbot         # terminal 2 — Telegram

The daemon step installs both processes (not only one):

• macOS — app.acpbot.host + app.acpbot.worker LaunchAgents (KeepAlive)
• Linux — acpbot-host.service + acpbot.service (systemd user)

Same ~/.config/acpbot/config.toml for host and worker (mode 600). Logs: ~/.local/share/acpbot/logs/ on macOS, or journalctl --user -u acpbot-host -u acpbot on Linux.

Day-to-day service control (on acpbot or acpbot-host):

acpbot-host install    # write + start both services
acpbot-host start
acpbot-host stop
acpbot-host restart
acpbot-host status
# host only: acpbot start --host

4. Pair as operator (CLI approve)

The bot starts unpaired. The first Telegram user does not get control automatically — you approve on the host CLI.

1. Open a private chat with the bot and send any message (e.g. /ping).
2. The bot replies with a pairing code (e.g. AB3K-9Q2M).
3. On the machine running acpbot, approve it:

acpbot pair list
acpbot pair approve AB3K-9Q2M
acpbot pair status

Telegram proves control of that account; the CLI proves control of the host (where the bot token lives). Only the approved user can control the bot afterward. Details: docs/pairing.md.

To re-pair another account: acpbot pair clear, then DM again and approve a new code.

5. Use Telegram

After pairing, use the private chat lobby and forum topics:

/ping
/new demo hello
# open the new forum topic → type a prompt

# useful topic commands
/status   /model   /agent   /mode   /skills   /mcp   /cancel
# while a turn is busy: free-text is queued
# /steer <text> interrupts · /queue · /unqueue

Speech (optional)

TTS and STT are independent. Providers: auto · openai · elevenlabs · off.

[speech]
tts_provider = "openai"
stt_provider = "openai"

[speech.openai]
api_key = "sk-…"
tts_voice = "alloy"
# tts_model = "tts-1"
# stt_model = "whisper-1"

More detail