11. WhatsApp Group Bot on Local Kubernetes (k3d + Colima + WAHA)

Group demo: @bot help	Bot log (real run, ids pseudonymised)

The k3d cluster: one node, WAHA pod 1/1 Running, NodePort service 3000:30000.

What you build

Two accounts: the bot runs on a second WhatsApp number (a spare SIM, or another number you own). Your main number owns the community/group and is the bot owner. People @mention the bot number; you control it privately.

Setup path

All commands run from the repo folder unless noted:

cd ~/path/to/google-sheets-mcp-guide

Part A · Container runtime (Colima, native arm64)

1Install and start Colima

brew install colima docker docker-compose k3d kubectl
colima start --arch aarch64 --vm-type vz --vz-rosetta --cpu 4 --memory 6
brew services start colima                     # start at every login

2Point Docker at Colima and check the architecture

docker context use colima
docker context show                            # colima
docker info --format '{{.Architecture}}'       # aarch64

If Docker Desktop is also installed, it can take the context back (desktop-linux) when it starts. Quit it and disable "Start at login", or re-run docker context use colima.

3Remove a global amd64 default (if you have one)

echo "DOCKER_DEFAULT_PLATFORM=$DOCKER_DEFAULT_PLATFORM"
grep -n DOCKER_DEFAULT_PLATFORM ~/.zshrc ~/.zprofile ~/.zshenv 2>/dev/null

If it prints linux/amd64, every pull asks for Intel images and WAHA's arm image fails with no matching manifest for linux/amd64. Comment it out (or unset it before these steps):

sed -i '' 's/^export DOCKER_DEFAULT_PLATFORM=/# &/' ~/.zshrc && source ~/.zshrc

Use --platform linux/amd64 per command when you really need an Intel image.

Part B · Local Kubernetes (k3d)

4Create the cluster

k8s/k3d-cluster.sh                 # or: k3d cluster create ts03 -p "127.0.0.1:3100:30000@server:0"
kubectl config current-context     # k3d-ts03
kubectl get nodes -o jsonpath='{.items[0].status.nodeInfo.architecture}{"\n"}'   # arm64

Why 3100: port 3000 is a common default (Open WebUI, Grafana, dev servers). Check what holds it with docker ps --format "table {{.Names}}\t{{.Ports}}" | grep 3000. WAHA keeps port 3000 inside the cluster; only the host side is 3100. Binding to 127.0.0.1 keeps it off your Wi-Fi.

Script: k8s/k3d-cluster.sh

Part C · Bot config and service

5Install the bot and create its config

mkdir -p ~/.local/bin ~/.config
cp scripts/ts03-bot ~/.local/bin/ && chmod +x ~/.local/bin/ts03-bot
cp templates/ts03-bot.env.example ~/.config/ts03-bot.env
sed -i '' "s|^WAHA_KEY=.*|WAHA_KEY=$(openssl rand -hex 16)|; s|^HOOK_SECRET=.*|HOOK_SECRET=$(openssl rand -hex 16)|" ~/.config/ts03-bot.env
chmod 600 ~/.config/ts03-bot.env
grep -E "^(WAHA_URL|WAHA_KEY|HOOK_SECRET)=" ~/.config/ts03-bot.env

Template: templates/ts03-bot.env.example. Set BOT_BUILDER and BOT_CONTACT to what members should see.

6Start the bot (webhook listener) first

scripts/install-bot.sh whatsapp
tail -3 ~/Library/Logs/ts03-bot.log            # "whatsapp webhook listening on :5055"

If macOS asks whether Python may accept incoming connections: Allow (the cluster reaches the bot through the VM network, not loopback).

Part D · Secret and webhook path

7Load the values into this terminal

set -a; source ~/.config/ts03-bot.env; set +a

8Create the namespace and secret

kubectl create namespace waha
kubectl -n waha create secret generic waha-secrets \
  --from-literal=WAHA_API_KEY="$WAHA_KEY" --from-literal=HOOK_SECRET="$HOOK_SECRET"
kubectl -n waha get secret waha-secrets -o jsonpath='{.data.WAHA_API_KEY}' | base64 -d | wc -c   # 32

9Find the host name pods can use to reach the bot

for H in host.k3d.internal host.docker.internal host.lima.internal $(ipconfig getifaddr en0); do
  printf "%-22s " "$H"
  kubectl run hooktest --rm -i --restart=Never --quiet --image=curlimages/curl -- \
    -s -o /dev/null -w "%{http_code}\n" --max-time 5 -X POST "http://$H:5055/hook/$HOOK_SECRET" -d '{}' 2>/dev/null || echo "unreachable"
done

Real result on Colima + k3d:

host.k3d.internal      200   ✅ use this (built into k3d, stable)
host.docker.internal   200
host.lima.internal     000
192.168.x.x            200   (works, but your LAN IP can change)

The manifest uses host.k3d.internal. If yours differs, edit WHATSAPP_HOOK_URL in k8s/waha.yaml.

Part E · Deploy WAHA

10Apply the manifest

kubectl apply -f k8s/waha.yaml
kubectl -n waha rollout status deploy/waha        # first pull takes a few minutes
kubectl -n waha get all

Manifest: k8s/waha.yaml (Namespace, PVC for the WhatsApp session, Deployment with replicas: 1 + Recreate, NodePort Service).

11Verify the API

curl -s -H "X-Api-Key: $WAHA_KEY" "http://127.0.0.1:3100/api/sessions"; echo    # []

Don't bother with k3d image import for multi-platform images: with Docker's newer image store it fails with content digest ... not found while printing "Successfully imported". Letting the node pull :arm works. If you need offline import: docker save --platform linux/arm64 devlikeapro/waha:arm -o waha.tar && k3d image import waha.tar -c ts03.

Part F · Link the bot's WhatsApp number

12Start the session and scan the QR (with the bot phone)

curl -s -X POST -H "X-Api-Key: $WAHA_KEY" -H "Content-Type: application/json" \
  "http://127.0.0.1:3100/api/sessions/start" -d '{"name":"default"}'; echo
sleep 8
curl -s -H "X-Api-Key: $WAHA_KEY" "http://127.0.0.1:3100/api/default/auth/qr?format=image" -o /tmp/waha-qr.png && open /tmp/waha-qr.png

Bot phone → WhatsApp → Settings → Linked devices → Link a device → scan (QR expires in ~20 s, re-run the last line for a fresh one).

curl -s -H "X-Api-Key: $WAHA_KEY" "http://127.0.0.1:3100/api/sessions"; echo

✅ "status":"WORKING" and a me block with id (<number>@c.us) and lid (<lid>@lid). Put both in SELF_IDS so real @mentions of the bot are recognised:

sed -i '' 's|^SELF_IDS=.*|SELF_IDS=<me.id>,<me.lid>|' ~/.config/ts03-bot.env

13Give the bot a name

Bot phone → WhatsApp → Settings → your name → TS-03 Tracker Bot. That's the name members see.

Part G · Owner, group and allowlist

14Create the group and add the bot

From your main number: community → Add group → Create new group (e.g. TS-03 Tracker Bot 🤖) → add the bot number as a member.

15Get the ids with /whoami

/whoami answers before anything is allowlisted:

16Configure and restart

nano ~/.config/ts03-bot.env

OWNER_ID=<your sender id>
OWNER_ALIASES=<your other id form, e.g. <number>@c.us>
ALLOWED_CHATS=<group chat id>@g.us
ALLOW_SELF_CHAT=0

scripts/install-bot.sh whatsapp --digest 08:00     # --digest: morning brief at 08:00 (DIGEST_CHAT or owner)

Part H · Prove the member sandbox is empty

Members' questions are untrusted text. They never reach your tools:

17Run the selftest

ts03-bot selftest; echo "exit=$?"

✅ Required before inviting anyone:

--tools "" supported: True
loaded tools      : none
loaded MCP servers: none
canary read       : blocked ✅
RESULT: ✅ sandbox has no tools, no MCP, and cannot read files
exit=0

It checks Claude Code's own session metadata (stream-json init event) and tries to read a secret canary file. It does not trust the model describing itself (that answer varies between runs). Re-run after every claude update: new built-in tools appear in releases.

Part I · Snapshot, subjects and the demo

18Build the snapshot

Private chat with the bot: /refresh

grep "snapshot refreshed" ~/Library/Logs/ts03-bot.log | tail -1
# snapshot refreshed: 5 items, 5 subjects

The snapshot holds every item (with full notes) plus the subject list from the Color Legend tab (subject, professors, TA). A hidden leftover row still counts: if you see an extra subject, unhide and delete it in the sheet, then /refresh.

19Run the demo in the group

One message at a time:

Command reference

For everyone in the group

Formats: add at the end of any command or question: table · json · yaml (also in json format, as a table, --yaml, in tabular form please). Default is cards (CHAT_FORMAT).

Triggers: a message must start with /, contain @bot, or @mention the bot account. Everything else in the group is ignored.

Owner only (your number)

No command deletes rows or clears tabs: those MCP tools are denied in ~/.claude/settings.json (Guide 3).

Operations

# health
kubectl -n waha get pods
curl -s -H "X-Api-Key: $WAHA_KEY" "http://127.0.0.1:3100/api/sessions"; echo
launchctl list | grep ts03.bot
tail -f ~/Library/Logs/ts03-bot.log

# restart pieces
kubectl -n waha rollout restart deploy/waha          # session persists on the PVC
scripts/install-bot.sh whatsapp --digest 08:00       # after editing ts03-bot.env

# after a Mac reboot (if needed)
docker context use colima && k3d cluster start ts03

# after `claude update`
ts03-bot selftest; echo "exit=$?"

# update the bot script
cp scripts/ts03-bot ~/.local/bin/ts03-bot && ts03-bot selftest && scripts/install-bot.sh whatsapp --digest 08:00

# remove everything
scripts/install-bot.sh whatsapp --uninstall
k3d cluster delete ts03

Troubleshooting (every error hit while building this)

Security checklist

• [ ] Bot runs on a second number, never your main one
• [ ] WAHA only on 127.0.0.1:3100, API key required; webhook only answers /hook/<HOOK_SECRET>
• [ ] ~/.config/ts03-bot.env is chmod 600, never committed
• [ ] ts03-bot selftest = ✅ (and re-run after every claude update)
• [ ] OWNER_ID / OWNER_ALIASES = only you; ALLOWED_CHATS = only the bot group
• [ ] Delete/clear MCP tools denied in ~/.claude/settings.json
• [ ] Members know answers can be up to 30 min old and must verify on Google Classroom
• [ ] Screenshots for sharing: pseudonymise WhatsApp ids (...@lid, [email protected]), phone numbers and classmates' names

Files for this guide

⬅️ Guide 10: Output formats · Option 6 overview · All guides