# Metaclaw > Node.js orchestrator for Claude agents running in isolated containers, controlled through messaging channels. - **Type:** MCP server - **Install:** `agentstack add mcp-charles-adedotun-metaclaw` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [charles-adedotun](https://agentstack.voostack.com/s/charles-adedotun) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [charles-adedotun](https://github.com/charles-adedotun) - **Source:** https://github.com/charles-adedotun/metaclaw ## Install ```sh agentstack add mcp-charles-adedotun-metaclaw ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # MetaClaw A Node.js orchestrator that routes WhatsApp and Telegram messages to Claude agents running in isolated Docker containers. ## What It Is MetaClaw is a single Node.js process that bridges messaging channels (WhatsApp, Telegram) to Claude Code running inside per-group Docker containers. Each registered group — a "Chief of Staff", a Researcher, an Engineer — gets its own container with isolated filesystem, session state, and a system prompt defined in a plain Markdown file. Agents respond to chat messages, execute cron-scheduled tasks, and communicate back to the host through a small filesystem IPC protocol. The value proposition is simple: give chat-based agents useful tools, persistent memory, and scheduled work, while keeping their shell access behind Docker instead of your host machine. The codebase is deliberately small (~30 TypeScript source files) so the operator can read and own the whole thing. ## Proof You Can Run For a fast source-level check: ```bash npm install npm run typecheck npm test ``` What this proves: the TypeScript host process compiles, and the Vitest suite exercises routing, queueing, IPC authorization, scheduler behavior, container timeout handling, and container-runtime command construction. For a container-boundary check: ```bash ./container/build.sh docker run --rm --entrypoint sh metaclaw-agent:latest -lc 'id -un && pwd' docker run --rm --entrypoint sh -v "$PWD:/workspace/project:ro" metaclaw-agent:latest -lc 'touch /workspace/project/.metaclaw-write-test 2>/dev/null || echo project-read-only' ``` Expected output: the first Docker command prints `node` and `/workspace/group`, showing the image runs as the non-root container user in the group workspace. The second command prints `project-read-only`, matching the main-agent mount policy in `src/container-runner.ts`: the project root is mounted read-only, while writable state is limited to explicit group, IPC, upload, session, and allowlisted extra mounts. ## Architecture ```mermaid flowchart LR chat["WhatsApp / Telegram"] --> db["SQLite message store"] db --> loop["Host message loop"] scheduler["Task scheduler"] --> runner["GroupQueue"] loop --> runner runner --> container["Per-group Docker container"] container --> claude["Claude Code + skills"] claude --> ipc["Filesystem IPC"] ipc --> host["Host IPC watcher"] host --> chat ``` - **Host orchestrator** (`src/index.ts`) — polls SQLite for new messages every 2 s, manages container lifecycle via `GroupQueue`, runs the IPC watcher and task scheduler in parallel loops. - **Per-group containers** — each group gets a separate Docker container running Claude Code via the `agent-runner` wrapper. Volume mounts are explicit and narrow: group workspace, IPC directory, uploads, and Claude session state. - **Filesystem IPC** — agents write JSON command files to `/workspace/ipc/messages/`. The host polls every 1 s and acts on `send_message`, `send_file`, `register_group`, `schedule_task`, and related commands. - **Skills** (`skills/`) — Claude Code skill definitions mounted read-only into every container. Built-in skills handle browser automation, document creation (PDF, DOCX, XLSX, PPTX), and file management. `/setup`, `/customize`, `/debug`, and `/update` skills handle the full operator workflow. - **Task scheduler** — SQLite-backed cron, interval, and one-shot tasks. Each task fires a container invocation with either a fresh or continuous Claude session. - **Mount security** — extra volume mounts are validated against an allowlist at `~/.config/metaclaw/mount-allowlist.json` before any container starts. ## Quickstart Requirements: Node.js 20+, Docker, Claude Code (the `claude` CLI). ```bash git clone https://github.com/charles-adedotun/metaclaw.git cd metaclaw cp .env.example .env # set ASSISTANT_NAME, and TELEGRAM_BOT_TOKEN if using Telegram npm install claude # open Claude Code in the project root ``` Inside Claude Code, run the setup skill: ``` /setup ``` The setup skill builds the container image, configures your channel, and installs the system service (launchd on macOS, systemd on Linux). For subsequent development: ```bash npm run dev # run with hot reload, no compile step npm run typecheck # type-check without emitting npm test # run all tests (vitest) ./container/build.sh # rebuild the agent container image ``` ## Why This Exists The typical multi-agent framework ends up as a configuration maze: multiple processes, overlapping permission layers, integrations no one asked for, and a codebase too large to audit confidently. MetaClaw is the opposite: one process, one database, containers as the security boundary instead of application-level permission checks. Bash is safe because it runs inside the container, not on your machine. Non-goals: - **Not a hosted platform.** This is self-hosted, single-operator software. - **Not a multi-tenant service.** No auth layer, no user management — you are the only operator. - **Not a configuration-driven framework.** If you want different behavior, change the TypeScript. The codebase is small enough that this is practical. New integrations are contributed as Claude Code skills (e.g. `/add-telegram`, `/add-discord`, `/convert-to-apple-container`) that transform the codebase on install, rather than adding runtime feature flags. ## Status Active development. The core orchestrator, container isolation, IPC protocol, and task scheduler are stable. The skills API and group configuration format may change between versions. Not recommended for production multi-user deployments. ## License [MIT](LICENSE) ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [charles-adedotun](https://github.com/charles-adedotun) - **Source:** [charles-adedotun/metaclaw](https://github.com/charles-adedotun/metaclaw) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-charles-adedotun-metaclaw - Seller: https://agentstack.voostack.com/s/charles-adedotun - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.