Build any bot you want. Connect any AI agent — Claude, GPT, a custom LLM, anything — to Telegram, Slack, HTTP, and more. You write the AI logic in any language; anyclaw handles message routing, crash recovery, tool access, and subprocess supervision.
⚠️ Unstable — anyclaw is under active development. APIs, config format, and protocol details may change between releases.
Anyclaw is infrastructure, not an AI framework. It's a sidecar process that sits between your agent and the outside world:
- Channels deliver messages to and from users (Telegram, HTTP, and more coming)
- Agents are your AI backends — any binary that speaks ACP (JSON-RPC 2.0 over stdio)
- Tools give agents capabilities via MCP servers managed by anyclaw
- Services provide infrastructure (credential-injecting proxy, media store)
All are standalone binaries spawned as child processes. Write them in Rust, Python, Go, TypeScript — whatever you prefer. Anyclaw manages their lifecycle, restarts them on crash, and routes messages between them.
Anyclaw does not:
- Run your agent logic — Your agent is a separate binary. Anyclaw spawns it and talks to it over stdio.
- Manage memory or context — Context windows, RAG, vector stores — that's your agent's job.
- Track costs or budgets — Token counting belongs in the agent, not infrastructure.
- Orchestrate multi-agent workflows — No built-in task routing or delegation.
- Choose which LLM to call — Anyclaw doesn't know or care what model your agent uses.
This boundary is intentional. See Introduction for the full design philosophy and ADR-001 for why.
See anyclaw running in under a minute — no API keys needed:
git clone https://github.com/donbader/anyclaw.git
cd anyclaw/examples/01-fake-agent-telegram-bot
cp .env.example .env
docker compose upIn another terminal, send a message:
curl -X POST http://localhost:8080/message \
-H "Content-Type: application/json" \
-d '{"message": "hello"}'You'll see the mock agent "think" and respond with Echo: hello. That's the full pipeline — channel receives message, routes to agent, agent streams response back.
Want to connect Telegram? Add your bot token to .env and set TELEGRAM_ENABLED=true. See the Getting Started guide for deploying with a real agent.
Anyclaw ships with these extensions in ext/, ready to use:
| Type | Name | Description |
|---|---|---|
| Agent | agent-mock | Echo agent with simulated thinking (for testing) |
| Channel | channel-telegram | Telegram bot integration |
| Channel | channel-debug-http | HTTP + SSE endpoint for development and testing |
| Tool | tool-system-info | Demo MCP tool returning system information |
| Tool | tool-send-file | Deliver files from agent to channel users |
| Service | service-proxy | Credential-injecting outbound proxy (L4/L7 MITM) |
| Service | service-media | Media store for cross-boundary file transfer with auto image compression |
We're actively growing this collection. If you build a channel, tool, or agent adapter that others would find useful, consider contributing it.
Extensions are standalone binaries communicating over stdio — no SDK dependency required. The Rust SDK crates handle protocol framing for you, but you can also speak the wire protocol directly from any language.
| Crate | What it does | docs.rs |
|---|---|---|
anyclaw-sdk-channel |
Build channel integrations (Telegram, Slack, etc.) | docs |
anyclaw-sdk-tool |
Build MCP-compatible tool servers | docs |
anyclaw-sdk-service |
Build infrastructure services (proxy, media store, etc.) | docs |
anyclaw-sdk-types |
Shared wire types used across all SDK crates | docs |
anyclaw-sdk-agent |
Supervisor-side hooks for intercepting agent messages | docs |
For channels and tools, implement a trait and hand it to the SDK harness — it handles all JSON-RPC/MCP framing. Agents speak the ACP wire protocol directly and don't need an SDK crate.
See Building Extensions for the full guide, including how to build extensions in non-Rust languages.
We're working toward a stable v1.0. Here's where things stand:
| Feature | Status | Notes |
|---|---|---|
| Five-component supervisor (services → orchestrator → tools+channels → agents) | ✅ | |
| Per-subprocess crash recovery with exponential backoff | ✅ | |
| Crash loop detection and escalation | ✅ | |
| Graceful shutdown with per-service timeouts | ✅ | |
| Health check loop + admin HTTP server | ✅ | Includes Prometheus /metrics endpoint |
YAML config with !env tag resolution and validation |
✅ | |
JSON Schema for anyclaw.yaml (IDE autocomplete) |
✅ | anyclaw schema CLI command |
Config validation CLI (anyclaw validate) |
✅ | Offline schema + semantic validation with --strict mode |
| Structured JSON logging | ✅ | log_format: json for production log aggregators |
| Extension defaults via initialize handshake | ✅ | |
| Agent-initiated messages | ✅ | Via standard session/update notifications (agents self-prompt internally) |
| Rich media delivery | ✅ | Images, files, audio between agents and channels (both directions) |
| Reply/thread context | ✅ | Agent knows which message the user is replying to |
| Credential-injecting outbound proxy | ✅ experimental | L7 MITM with per-host rules; merged CA bundle covers ~99% of HTTP libraries. See proxy limitations |
| Custom auth providers | ✅ | External binaries for short-lived tokens (GitHub App, OAuth2); cached with TTL + stampede protection |
| Credential leak detection | ✅ | Blocks outbound requests containing known secrets (echo detection + pattern matching) |
| Extensible services layer (ServicesManager) | ✅ | Installation protocol, health-based restart with backoff, crash-loop detection |
| Transparent proxy via iptables DNAT | ✅ | Deny-by-default networking for Docker agents; no client-side proxy config needed |
| Path-based filtering in proxy rules | ✅ | Fine-grained allow/deny per URL path, not just per host |
| Per-deployment namespace (Docker resource scoping) | ✅ | Isolates containers/networks per deployment to avoid collisions |
| Parallel manager initialization | ✅ | Tools+Channels boot concurrently for faster startup |
| Media store service (claim-check file transfer) | ✅ | Eliminates base64 overhead; auto-compresses images on upload |
| Host-side credential injection (MCP tool) | planned | Agent calls http_request tool instead of making direct HTTPS calls — 100% library coverage, no CA trust needed |
| Rate limiting | planned | Per-session and per-channel depth caps with backpressure |
| Supervisor management API | planned | Authenticated HTTP API for session introspection, agent control, and runtime status |
anyclaw doctor |
planned | Config validation, binary probes, channel connectivity checks |
| Feature | Status | Notes |
|---|---|---|
| ACP protocol (JSON-RPC 2.0 over stdio) | ✅ | Uses official agent-client-protocol SDK for typed dispatch and wire types |
| ACP↔HTTP bridge (connect any REST/SSE agent) | ✅ | |
| Docker workspace (run agents in containers) | ✅ | |
| Docker container hardening | ✅ | cap_drop: ALL, read-only rootfs, tmpfs — applied to all Docker agents |
| Network isolation via outbound proxy | ✅ experimental | Deny-by-default; only configured hosts reachable from agent containers |
| Session persistence (SQLite-backed) | ✅ | |
| Session recovery after crash | ✅ | Resume preferred; falls back to history replay |
| Session fork and list | ✅ | session/fork and session/list ACP methods (capability-gated) |
| Filesystem sandboxing | ✅ | |
| Permission system (agent → user approval flow) | ✅ | |
Platform commands (/new, /cancel) |
✅ | Built-in slash commands intercepted by the sidecar |
| Dynamic command menus | ✅ | Agents push available_commands_update to channels at runtime |
| Agent worker pool (concurrent sessions) | ✅ | Per-agent pool with sticky session affinity; scales between min_workers and max_workers |
| Full ACP spec compliance | in progress | SDK foundation added; wiring typed dispatch into manager is next |
| Agent-to-agent communication | planned | Handoff, delegation, or direct IPC between agents |
| Feature | Status | Notes |
|---|---|---|
| Telegram | ✅ | |
| Debug HTTP (development + testing) | ✅ | |
| Telegram: reply/thread context | ✅ | Sender attribution, partial quotes, media placeholders, openclaw-compatible format |
| Telegram: external/cross-chat reply context | planned | Handle external_reply for replies to messages from other chats |
| Telegram: reply media download | ✅ | Photos from replies downloaded; other media types show placeholder |
| Telegram: reply context access control | ✅ | Suppress reply context in groups when original sender is not in allowlist |
| Telegram: group/user allowlists | ✅ | Control who can interact with the agent via access_control options |
| Telegram: hierarchical work message | ✅ | Pinned header with flat tool display and per-tool emoji |
| Telegram: configurable rate limits | ✅ | Per-channel rate limit tuning via options |
| Feature | Status | Notes |
|---|---|---|
| MCP server hosting (external tool binaries) | ✅ | |
| Send-file tool (agent → user file delivery) | ✅ | Path-based; works across Docker boundaries via media store |
| Cross-boundary file sharing (agent ↔ tool) | ✅ | Media store with claim-check architecture; auto image compression |
| Feature | Status | Notes |
|---|---|---|
| Channel, Tool, Types, Agent, Service SDK crates on crates.io | ✅ | |
| Automated releases via release-plz | ✅ | |
| Stable API with semver guarantees | planned |
| Feature | Status | Notes |
|---|---|---|
| Multi-arch Docker images (amd64 + arm64) | ✅ | |
| PR-only workflow with conventional commit enforcement | ✅ | |
| Security audit + Trivy scanning | ✅ | |
Separate ext/ image (ghcr.io/donbader/anyclaw-ext) |
✅ | Extensions built independently from core |
| Independent extension versioning | planned | Per-extension semver after SDK types reach 1.0 |
Anyclaw is infrastructure — many features are best built as extensions rather than core. Here's what we'd love to see contributed:
| Extension | Type | Status | Notes |
|---|---|---|---|
| Slack | channel | planned | Same pattern as Telegram — use the Channel SDK |
| Discord | channel | planned | |
| Task scheduler | tool | planned | Cron/interval/one-shot task CRUD via MCP (execution trigger depends on agent-initiated messages) |
Some features live entirely in the agent, not in anyclaw — skills, prompt extensions, vector memory, and knowledge graphs are configured in your agent (e.g., CLAUDE.md, AGENTS.md, MCP servers). Anyclaw doesn't need to know about them.
Have an idea? Open a feature request.
cargo build # Build core workspace
cargo build --workspace --manifest-path ext/Cargo.toml # Build extension binaries
cargo test # Unit tests (core)
cargo test --workspace --manifest-path ext/Cargo.toml # Unit tests (extensions)
cargo clippy --workspace # Lint core
cargo clippy --workspace --manifest-path ext/Cargo.toml # Lint extensions
# Integration tests require ext/ binaries built first:
cargo build --workspace --manifest-path ext/Cargo.toml
cargo test -p anyclaw-integration-testsRust stable toolchain required. Check rust-toolchain.toml for the pinned version.
- Introduction — what anyclaw is, what it's not, design philosophy
- Architecture — five-manager system, boot order, protocols
- Security model — trust zones, container hardening, credential flow
- Installations — how services bind to agents, credential isolation
- Tool layers — when to put tools in the agent vs anyclaw layer
- ADR-001: Sidecar, not platform
- ADR-002: Subprocess, not library
- ADR-003: Multi-proxy credential isolation
- ADR-004: ACP over stdio
- ADR-005: No built-in budget tracking
- Getting started — copy an example, customize, deploy
- Proxy & credential security — outbound proxy, credential injection, leak detection
- Configuration reference — full
anyclaw.yamlschema - Deployment & container images — Docker image tags, platforms, usage
- Examples — ready-to-run setups (fake agent, OpenCode, Kiro, Claude Code, proxy sandbox)
- Changelog — release history
- Building extensions — start here: pattern overview, SDK vs wire protocol, testing
- ext/agents/AGENTS.md — ACP wire format (for building agent binaries in any language)
- ext/channels/AGENTS.md — Channel trait, harness, testing utilities
- ext/tools/AGENTS.md — Tool trait, MCP server
- Architecture overview — system design, protocol details
- Contributing guide — workflow, tests, PR process
- Project structure — workspace layout, where to find things
- Design principles — core invariants, anti-patterns
- Releasing — how releases work
- Support — how to get help
We welcome contributions — especially new channel integrations, tools, and agent variants. See CONTRIBUTING.md for the workflow, and check E-help-wanted issues for a starting point.
Architecture overview
┌─────────────────────────────────────┐
│ Supervisor │
│ (boot: services→orch→tools+chans→agents) │
└──────────────────┬──────────────────┘
│
┌────────────────────────────────────┼────────────────────────────────────┐
│ │ │ │
┌────▼─────┐ ┌──────▼────────┐ ┌───────▼──────────┐ ┌─────────▼──────────┐
│ Services │ │ ToolsManager │ │ AgentsManager │ │ ChannelsManager │
│ Manager │ │ │ │ │ │ │
│ proxy │ │ MCP servers │ │ ACP subprocess │ │ Telegram │
│ media │ │ │ │ (JSON-RPC/stdio)│ │ debug-http │
└────┬─────┘ └──────┬────────┘ └───────┬──────────┘ └─────────┬──────────┘
│ │ │ │
└────────┐ └───────┐ ┌──────┘ ┌────────────────────┘
▼ ▼ ▼ ▼
┌──────────────────────────────┐
│ Orchestrator │
│ routing · access · tools │
└──────────────────────────────┘
All cross-service communication goes through the Orchestrator via OrchestratorSender. No shared mutable state crosses service boundaries. The Orchestrator owns session routing, access control, and tool permission enforcement. Each subprocess has its own crash recovery loop with exponential backoff.
Boot order is services → orchestrator → tools+channels (parallel) → agents. Services boot first (proxy must be ready before agents make network calls). Orchestrator boots next so managers can send messages during initialization. Tools and channels boot in parallel. Agents boot last because they need tool URLs and channels ready. Shutdown is reverse: channels → agents → tools → orchestrator → services.
The outbound proxy uses TLS MITM to inject credentials into HTTPS requests. For this to work, the agent's HTTP client must trust the proxy's ephemeral CA certificate. Anyclaw handles this automatically by:
- Building a merged CA bundle (system root certs + proxy CA) at startup
- Writing it to the
anyclaw-sharedvolume at/anyclaw-shared/certs/ca-certificates.crt - Setting
SSL_CERT_FILE,REQUESTS_CA_BUNDLE,CURL_CA_BUNDLE,GIT_SSL_CAINFOto the merged bundle - Setting
NODE_EXTRA_CA_CERTSto the proxy CA cert alone (Node.js appends to system roots)
This covers ~99% of HTTP libraries (OpenSSL, curl, Python requests, Go net/http, rustls with native-roots, Node.js). The remaining ~1% are libraries that bundle their own root certs and ignore all env vars (e.g., reqwest with rustls-tls + webpki-roots).
For 100% coverage regardless of tech stack, we plan to add a host-side http_request MCP tool (similar to IronClaw's approach) where the agent calls a tool instead of making direct HTTPS calls. The supervisor makes the real request, injects credentials, and returns the response — no proxy, no CA trust, no TLS compatibility concerns.
Anyclaw draws inspiration from these projects:
- nanoclaw — lightweight TypeScript personal AI assistant bridging messaging channels to Claude agents in isolated containers
- openclaw — feature-rich TypeScript AI assistant gateway with 20+ channel integrations and an ACP bridge. Anyclaw's Orchestrator component (centralized message routing, access control, tool permissions) is directly inspired by openclaw's gateway architecture.
- ironclaw — Rust personal AI assistant with WASM-sandboxed tools, MCP support, and PostgreSQL-backed memory
Where these projects are complete AI assistants, anyclaw takes their architectural ideas — channel abstraction, tool sandboxing, protocol-driven communication — and applies them as a standalone infrastructure layer that any agent can plug into.
Licensed under either of:
at your option.