https://github.com/donbader/anyclaw
Infrastructure sidecar connecting AI agents to channels and tools
https://github.com/donbader/anyclaw
ai-agents infrastructure mcp rust sidecar
Last synced: about 1 month ago
JSON representation
Infrastructure sidecar connecting AI agents to channels and tools
- Host: GitHub
- URL: https://github.com/donbader/anyclaw
- Owner: donbader
- License: other
- Created: 2026-04-11T03:58:59.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-08T09:36:33.000Z (about 1 month ago)
- Last Synced: 2026-05-08T09:41:23.341Z (about 1 month ago)
- Topics: ai-agents, infrastructure, mcp, rust, sidecar
- Language: Rust
- Homepage:
- Size: 5.33 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-APACHE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# anyclaw
[](https://github.com/donbader/anyclaw/actions/workflows/ci.yml)
[](https://codecov.io/gh/donbader/anyclaw)
[](https://scorecard.dev/viewer/?uri=github.com/donbader/anyclaw)
[](https://crates.io/crates/anyclaw-sdk-types)
[](https://docs.rs/anyclaw-sdk-types)
[](https://github.com/donbader/anyclaw/blob/main/Cargo.toml)
[](LICENSE-MIT)
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.
## What is anyclaw?
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](ext/agents/AGENTS.md) (JSON-RPC 2.0 over stdio)
- **Tools** give agents capabilities via [MCP](https://modelcontextprotocol.io/) 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.
## What anyclaw is NOT
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](docs/introduction.md) for the full design philosophy and [ADR-001](docs/decisions/001-sidecar-not-platform.md) for why.
## Quickstart
See anyclaw running in under a minute — no API keys needed:
```bash
git clone https://github.com/donbader/anyclaw.git
cd anyclaw/examples/01-fake-agent-telegram-bot
cp .env.example .env
docker compose up
```
In another terminal, send a message:
```bash
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](docs/guides/getting-started.md) for deploying with a real agent.
## Built-in Extensions
Anyclaw ships with these extensions in [`ext/`](ext/), ready to use:
| Type | Name | Description |
|------|------|-------------|
| Agent | [agent-mock](ext/agents/mock/) | Echo agent with simulated thinking (for testing) |
| Channel | [channel-telegram](ext/channels/telegram/) | Telegram bot integration |
| Channel | [channel-debug-http](ext/channels/debug-http/) | HTTP + SSE endpoint for development and testing |
| Tool | [tool-system-info](ext/tools/system-info/) | Demo MCP tool returning system information |
| Tool | [tool-send-file](ext/tools/send-file/) | Deliver files from agent to channel users |
| Service | [service-proxy](ext/services/proxy/) | Credential-injecting outbound proxy (L4/L7 MITM) |
| Service | [service-media](ext/services/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](CONTRIBUTING.md).
## Build Your Own
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](https://docs.rs/anyclaw-sdk-channel) |
| `anyclaw-sdk-tool` | Build MCP-compatible tool servers | [docs](https://docs.rs/anyclaw-sdk-tool) |
| `anyclaw-sdk-service` | Build infrastructure services (proxy, media store, etc.) | [docs](https://docs.rs/anyclaw-sdk-service) |
| `anyclaw-sdk-types` | Shared wire types used across all SDK crates | [docs](https://docs.rs/anyclaw-sdk-types) |
| `anyclaw-sdk-agent` | Supervisor-side hooks for intercepting agent messages | [docs](https://docs.rs/anyclaw-sdk-agent) |
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](ext/agents/AGENTS.md) directly and don't need an SDK crate.
See [Building Extensions](docs/concepts/extensions.md) for the full guide, including how to build extensions in non-Rust languages.
## Roadmap
We're working toward a stable v1.0. Here's where things stand:
### Core
| 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](#proxy-ca-trust) |
| 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 |
### Agents
| 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 |
### Channels
| 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` |
### Tools
| 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 |
### SDK
| Feature | Status | Notes |
|---------|--------|-------|
| Channel, Tool, Types, Agent, Service SDK crates on crates.io | ✅ | |
| Automated releases via release-plz | ✅ | |
| Stable API with semver guarantees | planned | |
### CI/CD & Release
| 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 |
### Extension Ideas
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](https://docs.rs/anyclaw-sdk-channel) |
| 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](https://github.com/donbader/anyclaw/issues/new?template=feature_request.yml).
## Building from Source
```bash
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-tests
```
Rust stable toolchain required. Check `rust-toolchain.toml` for the pinned version.
## Documentation
### Understanding anyclaw
- [Introduction](docs/introduction.md) — what anyclaw is, what it's not, design philosophy
- [Architecture](docs/concepts/architecture.md) — five-manager system, boot order, protocols
- [Security model](docs/concepts/security-model.md) — trust zones, container hardening, credential flow
- [Installations](docs/concepts/installations.md) — how services bind to agents, credential isolation
- [Tool layers](docs/concepts/tool-layers.md) — when to put tools in the agent vs anyclaw layer
### Design decisions
- [ADR-001: Sidecar, not platform](docs/decisions/001-sidecar-not-platform.md)
- [ADR-002: Subprocess, not library](docs/decisions/002-subprocess-not-library.md)
- [ADR-003: Multi-proxy credential isolation](docs/decisions/003-multi-proxy-credential-isolation.md)
- [ADR-004: ACP over stdio](docs/decisions/004-acp-over-stdio.md)
- [ADR-005: No built-in budget tracking](docs/decisions/005-no-builtin-budget-tracking.md)
### For Users
- [Getting started](docs/guides/getting-started.md) — copy an example, customize, deploy
- [Proxy & credential security](docs/reference/proxy-security.md) — outbound proxy, credential injection, leak detection
- [Configuration reference](docs/reference/configuration.md) — full `anyclaw.yaml` schema
- [Deployment & container images](docs/guides/deployment.md) — Docker image tags, platforms, usage
- [Examples](examples/) — ready-to-run setups (fake agent, OpenCode, Kiro, Claude Code, proxy sandbox)
- [Changelog](CHANGELOG.md) — release history
### For Extension Builders
- [Building extensions](docs/concepts/extensions.md) — start here: pattern overview, SDK vs wire protocol, testing
- [ext/agents/AGENTS.md](ext/agents/AGENTS.md) — ACP wire format (for building agent binaries in any language)
- [ext/channels/AGENTS.md](ext/channels/AGENTS.md) — Channel trait, harness, testing utilities
- [ext/tools/AGENTS.md](ext/tools/AGENTS.md) — Tool trait, MCP server
- [Architecture overview](docs/concepts/architecture.md) — system design, protocol details
### For Contributors
- [Contributing guide](CONTRIBUTING.md) — workflow, tests, PR process
- [Project structure](docs/contributing/project-structure.md) — workspace layout, where to find things
- [Design principles](docs/contributing/design-principles.md) — core invariants, anti-patterns
- [Releasing](docs/contributing/releasing.md) — how releases work
- [Support](SUPPORT.md) — how to get help
## Contributing
We welcome contributions — especially new channel integrations, tools, and agent variants. See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, and check [`E-help-wanted`](https://github.com/donbader/anyclaw/labels/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.
## Inspiration
### Proxy CA Trust
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:
1. Building a merged CA bundle (system root certs + proxy CA) at startup
2. Writing it to the `anyclaw-shared` volume at `/anyclaw-shared/certs/ca-certificates.crt`
3. Setting `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `GIT_SSL_CAINFO` to the merged bundle
4. Setting `NODE_EXTRA_CA_CERTS` to 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](https://github.com/nearai/ironclaw)) 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.
## Inspiration
Anyclaw draws inspiration from these projects:
- [nanoclaw](https://github.com/qwibitai/nanoclaw) — lightweight TypeScript personal AI assistant bridging messaging channels to Claude agents in isolated containers
- [openclaw](https://github.com/openclaw/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](https://docs.openclaw.ai/concepts/architecture).
- [ironclaw](https://github.com/nearai/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.
## License
Licensed under either of:
- [MIT License](LICENSE-MIT)
- [Apache License, Version 2.0](LICENSE-APACHE)
at your option.