Self-hosted · MIT

Claude Code,
on WhatsApp.

AllosAgent is a self-hosted WhatsApp agent powered by Claude Code. No extra LLM API key. Runs on your machine. Multi-session. Multimodal.

Clone on GitHub Read the quickstart
  • python
  • cloudflared
  • claude-code
  • megaAPI-compatible
The problem

Building WhatsApp bots from scratch is expensive.

Every WhatsApp bot needs the same plumbing: a webhook, a tunnel, a message queue, a model, a sender. And every model needs its own API key, billing, and rate limits.

AllosAgent plugs your WhatsApp into a Claude Code session running on your machine. The Claude Code CLI is the LLM — no extra API key. Self-chat by default. Multi-session when you need it. Multimodal in, multimodal out.

How it works

Five hops, end to end.

WhatsApp message flow: WhatsApp → gateway → Cloudflare Tunnel → webhook server → Claude Code → reply
  1. 01

    Inbound

    WhatsApp delivers your message to the API gateway (megaAPI by default, or any compatible backend).

  2. 02

    Public URL

    Expose :3020 over HTTPS — localhost dev or self-hosted. Cloudflare Tunnel (Quick / named) by default; swap for ngrok, Tailscale Funnel, or your own reverse proxy.

  3. 03

    Webhook

    webhook_server.py validates the phone whitelist and writes a JSONL line per session.

  4. 04

    Claude Code

    The Claude Code session reads each line via the Monitor tool, processes the message, and crafts a reply.

  5. 05

    Outbound

    send_message.py sends the reply back through the gateway. Signature appended automatically. Loop guard built in.

Features

What you get out of the box.

Multimodal

Receive text, images, and audio. Reply with text and images. Audio transcription via OpenAI Whisper (optional).

Multi-session

One deployment can serve multiple WhatsApp instances. One Claude Code session per number.

Self-hosted

Runs on your laptop, your VPS, your Raspberry Pi. Tokens never leave your machine. Your WhatsApp number is whitelisted at the webhook layer.

Multi-model

Run any LLM that plugs into the Claude Code harness — Claude (Sonnet/Opus), Kimi K2.5 Turbo, MiniMax 2.7, GLM 5, Qwen, and more. Same Monitor, same tools, same prompt; swap the brain without touching the agent.

One-command bootstrap

python scripts/bootstrap.py runs the wizard, starts the webhook, opens the tunnel, registers the URL. Idempotent — re-run after every reboot.

Open source — MIT

Every line on GitHub. Contracts documented. Beads task graph. Built to be cloned and adapted.

Quickstart

From clone to first reply in three steps.

1

Clone & bootstrap

$ git clone https://github.com/giovani-junior-dev/Allos.git allos
$ cd allos
$ python scripts/bootstrap.py

Wizard asks for your gateway base URL, instance, token, and WhatsApp number. Public URL printed at the end.

2

Open Claude Code

$ claude

Open it inside the allos directory. The Monitor tool inherits your working directory.

3

Paste the activation prompt

Read CLAUDE_PROMPT.md and run the step 2 prompt. SESSION: 1

Then send a WhatsApp message to your own number. AllosAgent replies within seconds.

Don't have Python, git, curl, or cloudflared yet? Open Claude Code in an empty folder and paste the prompt in INSTALL_PROMPT.md — Claude installs every dependency (winget / brew / apt), clones the repo, and runs the bootstrap.

Provider-agnostic

Swap the WhatsApp gateway.

AllosAgent was built against megaAPI, but the host URL is a config field — not hardcoded. Any backend that mirrors the contract in docs/API_CONTRACT.md drops in by changing one value.

To switch — even mid-project — re-run the wizard with rm config.py && python -m whatsapp_agent.setup_config, enter the new base URL, and run python -m whatsapp_agent.update_webhooks.

Read the contract
Documentation

Everything you need to ship.

README

Architecture, prerequisites, repo layout.

INSTALL_PROMPT.md

Zero-to-running on a fresh machine via Claude Code.

SETUP.md

Slow path: gateway signup, named tunnel, multi-session.

CLAUDE_PROMPT.md

The exact prompt that activates AllosAgent inside Claude Code.

API_CONTRACT.md

Auth, endpoints, payloads. Required reading for clone authors.

TROUBLESHOOTING.md

Symptom → fix index. Cloudflared 404s, orphan monitors, signature loops.
FAQ

Common questions.

Do I need an Anthropic API key?
No. AllosAgent drives the Claude Code CLI session you already have open. The CLI is the LLM. No separate key.
Why megaAPI as the default gateway?
I'm the CEO of megaAPI — I picked it because non-technical users get a stable, supported WhatsApp gateway out of the box, with the security and reliability needed to run a real WhatsApp number safely. Developers who prefer another provider can swap by following docs/API_CONTRACT.md — same endpoints, same payloads, change one URL.
Can I use Kimi, GPT, or other models?
Yes. The prompt is validated against Anthropic Claude (best first-try behavior). Other models work with the defenses in CLAUDE.md and send_message.py.
Is my data private?
config.py is gitignored. The whitelist drops every message that isn't from your authorized number. The signature loop guard prevents echo replies. Tokens never leave your machine.
How do I contribute?
Read CONTRIBUTING.md, pick an open bd ready ticket, open a PR. Beads tracks dependencies; merge once tests pass.

Clone AllosAgent. Reply on WhatsApp tonight.

MIT-licensed. Self-hosted. No telemetry. No newsletter.

Clone on GitHub