telegram-claude-bot-operations

Telegram Claude Bot — Operations Guide

Service: telegram-claude-bot Host: bms-4 (54.36.123.110) Type: N8N workflow + tmux session manager Status: Active Implements: GitHub issue #608

---

Architecture

[Telegram user: radieu]
         |
         | /start /status /send /log /stop /restart
         v
[Telegram Bot API]
         |
         | webhook (HTTPS)
         v
[N8N BMS4 — n8n.bms-4.infra.zintegrowana.online]
  Telegram Trigger node
         |
         | Check authorized user (AUTHORIZED_TELEGRAM_ID)
         v
  Route Command (Switch node)
         |
    ┌────┴────┬──────┬──────┬──────┬──────┐
    v         v      v      v      v      v
 /status   /start  /stop /restart /send  /log
    |         |      |      |      |      |
    v         v      v      v      v      v
[Execute Command nodes — run as claude-runner via sudo]
         |
         | stdout/stderr
         v
  Send Telegram Reply (Markdown code block)
         |
         v
[Telegram user]

Components

Component	Location	Purpose
N8N workflow	BMS4 N8N instance	Telegram webhook → command routing → Execute Command
tmux sessions	BMS4, as claude-runner	Persistent Claude CLI sessions
setup.sh	infra-src/telegram-claude-bot/setup.sh	One-shot BMS4 configuration
sudoers snippet	/etc/sudoers.d/n8n-claude-runner	Allows N8N to run commands as claude-runner

Bot Commands Reference

Command	Shell command executed	Expected output
/status	tmux list-sessions + ps aux grep claude + free -h	Session list, PID, CPU/RAM
/start	tmux new-session -d -s claude-agent -x 220 -y 50	”Session claude-agent started”
/stop	tmux kill-session -t claude-agent	”Session claude-agent stopped”
/restart	kill + sleep 1 + start	”Session claude-agent restarted”
/send <prompt>	tmux send-keys … Enter; sleep 5; tmux capture-pane -p	Claude output (last 30 lines)
/log	tmux capture-pane -p -S -50	Last 50 lines of session

Security Model

• User allowlist: N8N workflow checks message.from.id against AUTHORIZED_TELEGRAM_ID env var
• No response to unauthorized: messages from other users are silently dropped (NoOp node)
• Credential storage: Telegram bot token lives in N8N credentials store only — never in git
• Process isolation: commands run as claude-runner (non-root) via sudo
• Sudoers scope: only /usr/bin/bash is permitted, not all commands

EU AI Act — Risk Classification

• Risk tier: limited (Art. 52 — transparency obligation only)
• Rationale: This is a remote control interface for human-initiated Claude sessions. No autonomous decision-making, no scoring of persons, no automated allocation. The human (radieu) sends every prompt explicitly.
• Transparency: The bot is operated by the owner for personal infrastructure management.

Daily Operations

Check bot is responding

Send /status from Telegram. If no response within 30 seconds:

1. SSH to BMS4: ssh ubuntu@54.36.123.110
2. Check N8N: docker compose -f /opt/n8n/docker-compose.yml ps
3. Check workflow is Active in N8N UI

Start a Claude session

/start

Then send prompts with /send <your prompt>.

View live session output

/log

Note: /send waits 5 seconds for output. For long-running tasks, use /log after a delay.

Kill and restart session

/restart

Deployment / Update Procedure

1. Edit infra-src/telegram-claude-bot/n8n-workflow.json
2. Merge PR to dev
3. SSH to BMS4, pull latest: cd /opt/p24-infra && git pull
4. Re-import workflow JSON in N8N (Workflows → Import from file → overwrite existing)
5. Re-select credentials in both Telegram nodes
6. Re-activate workflow

Incident Response

Bot not responding

1. Check N8N workflow is Active
2. docker compose logs n8n --tail=100 on BMS4
3. Restart N8N if needed: docker compose restart n8n
4. Verify Telegram webhook: N8N Telegram Trigger node → Test Step

tmux session disappeared

• Sessions are lost on server reboot or manual kill
• Just send /start to recreate

Claude process hung

/stop
/start

Related

• Setup guide: infra-src/telegram-claude-bot/README.md
• N8N workflow: infra-src/telegram-claude-bot/n8n-workflow.json
• Setup script: infra-src/telegram-claude-bot/setup.sh
• BMS4 operations: docs/servers/p4-ovh-bms-4-ns3101999-operations.md
• GitHub issue: https://github.com/radieu/p24-infra/issues/608