nanocoai/nanoclaw

NanoClaw – Secure, Container‑Isolated AI Assistants

What it is

• An open‑source framework that lets you run AI agents (Claude, OpenAI, Ollama, etc.) in separate Docker containers. Each agent has its own filesystem, memory and credentials, so the host machine stays isolated from the model’s execution.
• Designed to be tiny and understandable: a single Node.js process orchestrates everything, and the core code lives in a handful of files.

Key capabilities

Feature	What it does
Per‑agent container isolation	Every agent runs in its own Linux container; only the directories you explicitly mount are visible to it.
Multi‑channel messaging	Built‑in adapters for Slack, Discord, Telegram, WhatsApp, iMessage, Microsoft Teams, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, email (via Resend) and a local CLI. Add new adapters on‑demand with /add‑<channel> skills.
Credential gateway	API keys never touch the container. Outbound requests are proxied through a credential‑gateway service (OneCLI’s Agent Vault by default) that injects the right secret per‑agent and enforces rate limits.
Agent templates	Quickly spin up a ready‑to‑run agent from a template stored in templates/ or the public template library.
Scheduled tasks	Define recurring jobs (e.g., daily briefings) that the container executes only when needed, optionally guarded by script‑gates.
Hybrid AI‑native workflow	Installation and error‑recovery are scripted, but whenever a step needs judgment the system hands off to Claude Code (Anthropic’s “code‑assistant”) which can diagnose and continue automatically.
Zero‑config customization	Instead of editing sprawling config files you tell Claude Code what you want (e.g., change the trigger word) and it patches the source code for you.
Cross‑model support	Claude is the default provider, but you can add OpenAI Codex, OpenRouter via OpenCode, Cursor’s local SDK, or any Ollama model with simple /add‑<provider> commands.

Installation & quick start

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash nanoclaw.sh   # installs Node, pnpm, Docker if needed, registers Anthropic creds, builds the first agent container, and pairs a channel (Slack, Telegram, …)

The script walks you through every step; if something fails Claude Code is invoked automatically to debug and resume.

How you interact with an agent

• Choose a trigger word (default @Andy).
• Send natural‑language commands in any connected channel, e.g.:

  @Andy send an overview of the sales pipeline every weekday morning at 9 am (has access to my Obsidian vault folder)
  @Andy review the git history for the past week each Friday and update the README if there’s drift
  

• Manage groups, tasks and channel wiring with chat commands like @Andy list all scheduled tasks or @Andy join the Family Chat group.

Extending NanoClaw

• Skills – New functionality is added as skills rather than core features. A skill lives in its own folder (payload/) and is installed with a slash command (/add‑telegram, /add‑opencode, etc.).
• Channels – Channel adapters live on a dedicated channels branch; you can fork the repo, add a custom adapter, and copy it into your own installation.
• Providers – Alternate LLM back‑ends are added the same way, keeping the main codebase minimal.

Security model

• OS‑level isolation – Docker containers give each agent its own PID, network namespace and filesystem view.
• Credential handling – Secrets are stored only on the host and injected at request time by the credential gateway; containers never see raw keys.
• No user accounts – NanoClaw does not create cloud accounts. The only outbound connection is to the optional community portal for perks (e.g., a hardened pre‑built image or managed Slack app). All diagnostics are anonymous and can be disabled via NANOCLAW_NO_DIAGNOSTICS=1.

Typical use cases

• Personal productivity assistant that can read/write files in a private vault, schedule reports, and interact with version control.
• Secure, self‑hosted chatbot that can browse the web, fetch data, and act on behalf of the user without exposing API keys.
• Multi‑user team bots where each team member gets its own isolated agent but shares a common channel (e.g., a Slack workspace).
• Experimentation platform for trying out different LLM providers while keeping the runtime environment identical.

Community & support

• Discord community: https://discord.gg/VDdww8qS42
• Documentation site: https://docs.nanoclaw.dev
• Public template library: https://github.com/nanocoai/nanoclaw-templates

License

• MIT – free for personal, academic or commercial use.

---

NanoClaw aims to give power‑users a transparent, container‑isolated AI assistant that they can understand, audit and tailor without dealing with a massive monolithic codebase.