Skip to content
/
Tier B A8 Cross-runtime harness

NanoClaw

nanoclaw · nanocoai/nanoclaw · ★ 29k · last commit 2026-05-26

Run Claude agents securely in per-session Docker containers with multi-channel messaging (WhatsApp/Telegram/Discord) and credential vault isolation.

Best whenOS-level container isolation is non-negotiable; application-level permission checks are insufficient for personal AI assistants.
Skip ifConfiguration sprawl (use code changes instead), Bundling all features in trunk (use skills for channel adapters)
vs seeds
agent-os(personal harness philosophy) but adds true Docker container isolation (vs in-place execution), 49 infrastructure skills…
Primitive shape 49 total
Skills 49
00

Summary

NanoClaw — Summary

NanoClaw is a lightweight TypeScript harness that runs Claude agents inside per-session Docker Linux containers, providing OS-level filesystem isolation rather than application-level permission checks. Each registered agent group gets its own container, its own CLAUDE.md, its own memory, and only the filesystem mounts you explicitly allow. The project positions itself as a minimal, forkable alternative to the larger OpenClaw (~500k lines), keeping its own trunk small enough for a single developer to read in one sitting. Channel adapters (Telegram, Discord, WhatsApp, Slack, Gmail, etc.) are installed on-demand via /add-<channel> skills rather than bundled, so each fork stays lean. An SQLite-backed message bus routes inbound messages through the container boundary using two files per session (inbound.db → container → outbound.db) — no IPC, no stdin piping, no cross-mount contention. Optional micro-VM isolation via Docker Sandboxes or Apple Container is an opt-in layer on top of the Docker default. Credential security is delegated to OneCLI's Agent Vault, which injects API keys at request time so agent containers never hold raw credentials.

Differs from seeds: Closest to agent-os in "personal harness for one user" philosophy, but NanoClaw adds true container isolation (vs agent-os's in-place execution), a skill-driven channel marketplace, multi-channel routing (WhatsApp/Telegram/Discord/Slack simultaneously), and scheduled-task support. Unlike claude-flow's hive-mind orchestration, NanoClaw is single-agent-per-conversation with no peer-to-peer coordination. Unlike superpowers, NanoClaw ships zero workflow-methodology skills — its skills are infrastructure primitives (add channel, manage mounts, update harness).

01

Overview

NanoClaw — Overview

Origin

NanoClaw was created as a deliberate minimalist reaction to OpenClaw's complexity. The author's stated motivation (verbatim from README):

"OpenClaw is an impressive project, but I wouldn't have been able to sleep if I had given complex software I didn't understand full access to my life. OpenClaw has nearly half a million lines of code, 53 config files, and 70+ dependencies. Its security is at the application level (allowlists, pairing codes) rather than true OS-level isolation. Everything runs in one Node process with shared memory."

Philosophy (verbatim)

  • "Small enough to understand." One process, a few source files and no microservices.
  • "Secure by isolation." Agents run in Linux containers and they can only see what's explicitly mounted.
  • "Built for the individual user." NanoClaw isn't a monolithic framework; it's software that fits each user's exact needs.
  • "Customization = code changes." No configuration sprawl. Want different behavior? Modify the code.
  • "AI-native, hybrid by design." The install and onboarding flow is an optimized scripted path. When a step needs judgment, control hands off to Claude Code seamlessly.
  • "Skills over features." Trunk ships the registry and infrastructure, not specific channel adapters or alternative agent providers.
  • "Best harness, best model." NanoClaw natively uses Claude Code via Anthropic's official Claude Agent SDK.

Target User

Solo developers who want multi-channel AI messaging (WhatsApp, Telegram, Discord, etc.) with genuine security guarantees, without needing to trust a large opaque codebase.

Repo Facts

  • GitHub: https://github.com/nanocoai/nanoclaw (canonical; the batch-18 URL qwibitai/nanoclaw redirects here)
  • Stars: 29,431 (as of 2026-05-26)
  • Language: TypeScript (Bun runtime inside containers)
  • License: MIT
  • Last commit: 2026-05-26
  • v2 rewrite with migration script from v1
02

Architecture

NanoClaw — Architecture

Distribution

  • Type: Clone-and-configure (standalone repo, fork-it model)
  • Install: git clone https://github.com/nanocoai/nanoclaw.git && bash nanoclaw.sh
  • Runtime: Node.js 20+ / pnpm 10+ on host; Bun inside agent containers; Docker or Apple Container required
  • CLI Binary: ncl (Python-based claw CLI installed via /claw skill)

Message Flow

messaging apps → host process (router) → inbound.db → container (Bun, Claude Agent SDK) → outbound.db → host process (delivery) → messaging apps
  • Host Node.js process routes incoming messages via entity model (user → messaging group → agent group → session)
  • Writes to session's inbound.db, wakes the container
  • Container polls inbound.db, runs Claude Agent SDK, writes to outbound.db
  • Host polls outbound.db, delivers back through channel adapter

Key Design Choices

  • Two SQLite files per session: each with exactly one writer — no cross-mount contention, no IPC, no stdin piping
  • Channels and providers self-register at startup: trunk ships only the registry
  • Three-level isolation: see docs/isolation-model.md
    1. Basic Docker container (default)
    2. Docker Sandboxes (micro-VM isolation, optional)
    3. Apple Container (macOS-native micro-VM, optional)

Directory Tree

nanoclaw/
├── src/                    # TypeScript host process
│   ├── index.ts            # Entry point: DB init, channel adapters, delivery polls
│   ├── channels/           # Channel adapter registry
│   ├── container-runner.ts # Docker/Apple Container invocation
│   ├── db/                 # SQLite session state
│   └── cli/                # ncl CLI client
├── container/              # Agent container image (Dockerfile + Bun + Claude SDK)
├── .claude/
│   └── skills/             # 49 skills (add-<channel>, manage, migrate, etc.)
├── docs/                   # architecture.md, isolation-model.md, etc.
├── setup/                  # Interactive setup wizard
├── scripts/                # Utility scripts
├── nanoclaw.sh             # Full install + onboard script
├── migrate-v2.sh           # v1→v2 migration script
├── package.json            # bin: {ncl: "bin/ncl"}
└── .mcp.json               # MCP config (not a bundled server)

Target AI Tools

  • Claude Code (via Anthropic Claude Agent SDK) — primary
  • Codex (via /add-codex skill)
  • OpenCode/OpenRouter (via /add-opencode skill)
  • Ollama local models (via /add-ollama-provider skill)

Required Runtime

  • Node.js >= 20, pnpm >= 10 (host)
  • Docker Desktop (macOS/Windows) or Docker Engine (Linux)
  • macOS or Linux (WSL2 for Windows)
  • Claude Code for skill installation and error recovery
03

Components

NanoClaw — Components

Skills (49 total, in .claude/skills/)

Infrastructure / Setup

  • setup — Initial NanoClaw install; delegates to nanoclaw.sh
  • init-first-agent — Creates first agent group, promotes operator to owner, verifies delivery
  • init-onecli — Registers Anthropic credential with OneCLI Agent Vault
  • customize — Guided code-change workflow for personalizing the fork
  • debug — Diagnose and fix NanoClaw issues
  • update-nanoclaw — Pull latest changes and rebuild
  • update-skills — Update skills directory
  • migrate-nanoclaw — In-place NanoClaw migration
  • migrate-from-v1 — v1 → v2 data migration
  • migrate-from-openclaw — OpenClaw → NanoClaw migration

Channel Adapters (install-on-demand)

  • add-telegram — Add Telegram channel
  • add-discord — Add Discord channel
  • add-whatsapp — Add WhatsApp (official Cloud API)
  • add-whatsapp-cloud — WhatsApp Cloud API variant
  • add-slack — Add Slack channel
  • add-gmail-tool — Gmail integration
  • add-gcal-tool — Google Calendar integration
  • add-gchat — Google Chat channel
  • add-imessage — iMessage channel
  • add-matrix — Matrix channel
  • add-macos-statusbar — macOS menu bar channel
  • add-emacs — Emacs integration
  • add-github — GitHub integration
  • add-linear — Linear integration
  • add-deltachat — Delta Chat channel
  • add-atomic-chat-tool — Atomic Chat tool

Provider Adapters (alternate LLM backends)

  • add-codex — OpenAI Codex provider
  • add-opencode — OpenCode / OpenRouter / Google / DeepSeek provider
  • add-ollama-provider — Local Ollama provider
  • add-ollama-tool — Ollama as a tool (not provider)

Channel Management

  • manage-channels — Wire channels to agent groups, manage isolation levels
  • manage-mounts — Control filesystem mounts per agent container

Specialized Tools

  • claw — Install the claw Python CLI for terminal-to-container access
  • add-parallel — Parallel agent execution
  • convert-to-apple-container — Switch from Docker to Apple Container runtime
  • use-native-credential-proxy — OneCLI credential proxy setup
  • add-mnemon — Memory tool integration
  • add-karpathy-llm-wiki — Karpathy LLM wiki tool
  • add-dashboard — Web dashboard for monitoring
  • add-macos-statusbar — macOS status bar
  • get-qodo-rules — Fetch Qodo AI rules
  • qodo-pr-resolver — PR review with Qodo
  • x-integration — X (Twitter) integration

CLI Binaries

  • ncl — NanoClaw client CLI (bin/ncl, TypeScript/Node)
  • claw — Agent container invocation CLI (Python, installed via skill)

Container Image

  • nanoclaw-agent:latest — Bun + Claude Agent SDK + tool dependencies
  • Built via ./container/build.sh
  • Alpine Linux base

Database

  • data/v2.db — SQLite: agent_groups, messaging_groups, messaging_group_agents, user_roles, scheduled_tasks
  • Per-session: inbound.db, outbound.db (one writer each)

Config Files

  • .env — API keys, channel tokens (never exposed to containers)
  • CLAUDE.md / CLAUDE.local.md — Per-agent-group instructions
  • .mcp.json — MCP server configuration (not bundled)
05

Prompts

NanoClaw — Prompts

Verbatim Excerpt 1: claw Skill (.claude/skills/claw/SKILL.md)

---
name: claw
description: Install the claw CLI tool — run NanoClaw agent containers from the command line without opening a chat app.
---

# claw — NanoClaw CLI

`claw` is a Python CLI that sends prompts directly to a NanoClaw agent container from the terminal. It reads registered groups from the NanoClaw database, picks up secrets from `.env`, and pipes a JSON payload into a container run — no chat app required.
...
## Troubleshooting

### "neither 'container' nor 'docker' found"
Install Docker Desktop or Apple Container (macOS 15+), or pass `--runtime` explicitly.

### Container times out
The default timeout is 300 seconds. For longer tasks, pass `--timeout 600` (or higher).

Technique: Functional specification skill — describes a tool's behavior, usage patterns, and troubleshooting rather than behavioral rules. The skill IS the installation script + documentation rolled into one.

Verbatim Excerpt 2: manage-channels Skill (.claude/skills/manage-channels/SKILL.md)

---
name: manage-channels
description: Wire messaging channels to agent groups, manage isolation levels, add new channel groups. Use after adding a channel, during setup, or standalone to reconfigure.
---

# Manage Channels

Wire messaging channels to agent groups. See `docs/isolation-model.md` for the full isolation model.

Privilege is a **user-level** concept, not a channel-level one. There is no "main channel" / "main group" — any user can be granted `owner` or `admin` (global or scoped to an agent group) via `grantRole()`, and messages from unknown senders are gated per-messaging-group by `unknown_sender_policy` (`strict` | `request_approval` | `public`).

### Isolation Question
Present a multiple-choice with a contextual recommendation. The three options:
- **Same conversation** (`--session-mode "agent-shared"` + existing folder) — all messages land in one session.
- **Same agent, separate conversations** (`--session-mode "shared"` + existing folder) — shared workspace/memory, independent threads.
- **Separate agent** (new `--folder`) — full isolation.

Technique: Decision-tree skill with embedded SQL queries and shell commands. The skill directs Claude to query the live database before making recommendations, grounding decisions in actual runtime state rather than assumptions.

Verbatim Excerpt 3: setup Skill (.claude/skills/setup/SKILL.md)

---
name: setup
description: Run initial NanoClaw setup. Use when user wants to install NanoClaw, configure it, or go through first-time setup. Triggers on "setup", "install", "configure nanoclaw", or first-time setup requests.
---

# NanoClaw Setup

Tell the user to run `bash nanoclaw.sh` in their terminal. That script handles the full end-to-end setup — dependencies, container image, OneCLI vault, Anthropic credential, service, first agent, and optional channel wiring.

If they hit an error partway through, it will offer Claude-assisted recovery inline — no need to come back here.

Technique: Minimal delegation skill. Rather than encoding logic, this skill routes to an external shell script, keeping the skill as thin documentation of intent. Anti-pattern: never tries to replicate what nanoclaw.sh does.

09

Uniqueness

NanoClaw — Uniqueness & Positioning

differs_from_seeds

NanoClaw is closest to agent-os in its "personal harness for one individual" philosophy, but diverges architecturally on every major dimension: where agent-os writes files in-place with no isolation, NanoClaw wraps every agent session in a Docker Linux container (with optional micro-VM upgrade). Where agent-os ships 5 commands for writing markdown standards files, NanoClaw ships 49 skills for adding messaging channels and managing container infrastructure. NanoClaw's skill library is exclusively infrastructure primitives — it ships zero workflow methodology. Unlike claude-flow's hive-mind with 305 MCP tools and consensus protocols, NanoClaw is deliberately single-threaded per conversation. Unlike ccmemory's persistent Neo4j graph, NanoClaw stores state in SQLite with explicit mount-based memory isolation per agent group.

Distinctive Positioning

  1. Isolation as the primary value proposition: NanoClaw is explicitly built around the claim that OS-level container isolation > application-level permission checks. This is rare in the corpus.

  2. Fork-it model: NanoClaw is designed to be forked and customized via code changes, not configured. The README explicitly says "No configuration sprawl. Want different behavior? Modify the code."

  3. Skills as infrastructure primitives: 49 skills are all infrastructure (add channel, migrate, manage mounts) — not productivity tools. This is the inverse of superpowers/BMAD.

  4. Multi-channel routing as first-class: Channel routing (WhatsApp → agent-group-A, Telegram → agent-group-B) with three isolation modes (same-session / shared / separate-agent) is uniquely developed in this corpus.

  5. OneCLI credential vault integration: Credential injection at the proxy layer (never in container) is a security primitive not seen in other frameworks.

Observable Failure Modes

  • Requires Docker + Node.js — install complexity is real (multi-step, platform-dependent)
  • Channel adapters are on separate branches, not trunk — users must know to run /add-telegram etc.
  • v2 is a major rewrite; v1 users need migration
  • No structured audit log — debugging relies on SQLite queries
  • No out-of-the-box web UI (must install via skill)
  • Not portable: deeply tied to Claude Code + Anthropic Claude Agent SDK (other providers are add-ons)
04

Workflow

NanoClaw — Workflow

Setup Phase

Step Artifact Approval Gate
Run nanoclaw.sh Node + pnpm + Docker installed Scripted (auto)
Register Anthropic credential with OneCLI Agent Vault entry Manual (credential input)
Build agent container image nanoclaw-agent:latest Auto
Create first agent group DB row in agent_groups Manual (name choice)
Wire first channel DB row in messaging_groups + messaging_group_agents Manual (channel selection + platform ID)
Verify delivery (DM from agent) Welcome message received Human confirmation

Per-Session Flow

Step Artifact Notes
Message arrives via channel adapter Platform webhook/poll
Host routes to agent group via entity model inbound.db row DB write
Container wakes, polls inbound.db Claude Agent SDK invocation
Claude processes, uses tools Tool calls inside container Container-isolated
Response written to outbound.db DB write One writer per file
Host polls outbound.db, delivers back Channel-specific delivery

Channel Addition

Step Artifact
Run /add-<channel> skill Channel module copied to fork
Skill adds credentials to .env Token stored in OneCLI Vault
Run /manage-channels DB entities created, isolation level chosen
Test delivery Manual verification

Scheduled Tasks

  • Defined via natural language in chat ("every Monday at 8am...")
  • Stored in data/v2.db scheduled_tasks table
  • Host cron triggers container run with scheduled prompt

Approval Gates

  • Channel isolation model: prompted during /manage-channels (choice: same-session / shared / separate-agent)
  • Fork customization: no approval gates — code changes via Claude Code
  • Credential injection: OneCLI vault handles; agent never sees raw keys

Execution Mode

  • Continuous daemon: Host process runs 24/7, polling outbound.db and channel webhooks
  • Container instances are ephemeral per-session (spawned on demand)
06

Memory Context

NanoClaw — Memory & Context

State Storage

  • Session state: Two SQLite files per session (inbound.db, outbound.db) — ephemeral, per-container
  • Agent state: data/v2.db — persistent SQLite on host: agent_groups, messaging_groups, users, scheduled_tasks
  • Per-agent CLAUDE.md: Each agent group folder contains its own CLAUDE.md + CLAUDE.local.md for persistent behavioral instructions
  • Memory mount: Optional — each agent has explicit filesystem mounts; only mounted paths are visible inside the container

Persistence Model

  • Memory persists across sessions via:
    1. CLAUDE.md in the agent group folder (behavioral rules, preferences)
    2. Mounted directories (files the agent can read/write persistently)
    3. The data/v2.db scheduled-tasks table
    4. Optional /add-mnemon skill (Mnemon memory tool integration)

Context Compaction

  • Claude Agent SDK manages context window internally
  • NanoClaw has no explicit compaction hook — relies on SDK behavior
  • Per-agent CLAUDE.md limits context surface to relevant agent-group material

Cross-Session Handoff

  • Agent groups persist; session containers are ephemeral
  • A new container is spawned for each session but reads the same agent-group filesystem mounts
  • Session ID system enables resuming specific past sessions via claw -s <session-id>

Credential Security

  • Credentials stored in OneCLI Agent Vault on host
  • Injected at HTTP request time by OneCLI proxy
  • Agent containers NEVER receive raw API keys
  • Secrets file mounted into proxy sidecar only (not agent container)

Multi-Agent Memory Boundaries

  • Each agent group has its own container with its own mounts → strict memory isolation by default
  • Cross-agent memory sharing requires explicit mount configuration via /manage-mounts
  • Team workspaces (future feature) would share a PVC at /team
07

Orchestration

NanoClaw — Orchestration

Multi-Agent

NanoClaw supports multiple simultaneous agent groups, each running in their own container. Containers do NOT coordinate peer-to-peer — each responds independently to its assigned channel messages. There is no orchestrator-worker hierarchy within a session.

Optional: /add-parallel skill for parallel agent execution patterns.

Orchestration Pattern

  • Per-group: Single agent per conversation (sequential)
  • Cross-group: Independent containers, no coordination
  • Pattern classification: none (single-agent per session) / parallel-independent across groups

Isolation Mechanism

Primary: Docker container isolation

  • Agent container runs in Linux container with restricted filesystem access
  • Only explicitly mounted directories visible inside
  • Container spawned per-session; persistent state via SQLite host DB

Optional levels (from docs/isolation-model.md):

  1. Docker container (default — OS-level process isolation)
  2. Docker Sandboxes (micro-VM per container — stronger hypervisor isolation)
  3. Apple Container (macOS-native micro-VM via Apple Containerization framework)

Credential isolation: OneCLI Agent Vault injects credentials at request time; raw API keys never reach the container filesystem.

Multi-Model

  • Per-agent-group provider configuration: default is Claude Code (Claude Agent SDK)
  • Optional via skills: Codex (/add-codex), OpenCode/OpenRouter/Gemini (/add-opencode), Ollama (/add-ollama-provider)
  • Provider is configurable per agent group (not per-task)

Execution Mode

Continuous daemon: Host process runs 24/7 polling channel adapters and delivery queues. Container instances are on-demand (event-driven, spawned per session). Scheduled tasks add a cron-driven execution path.

Consensus Mechanism

None — no multi-agent consensus needed in single-group-per-conversation model.

Prompt Chaining

No explicit prompt chaining. Each container invocation is standalone.

08

Ui Cli Surface

NanoClaw — UI & CLI Surface

CLI Binaries

ncl (primary)

  • TypeScript/Node binary shipped in bin/ncl
  • Defined in package.json#bin: {ncl: "bin/ncl"}
  • Used for direct messaging and management from terminal

claw (Python, skill-installed)

  • Installed via /claw skill
  • Sends prompts directly to agent containers from terminal
  • Reads registered groups from data/v2.db
  • Supports: -g group selection, -s session resume, --pipe stdin mode, --list-groups, --runtime override, --timeout override
  • Outputs response to stdout, session ID to stderr

Local UI

No dedicated web dashboard shipped in trunk. The /add-dashboard skill installs a monitoring web dashboard on-demand (optional). launchd/ directory suggests macOS launchd service integration.

Channel Surfaces (User-Facing)

The UI surface IS the messaging channels:

  • WhatsApp, Telegram, Discord, Slack, Gmail, iMessage, Matrix, Google Chat, etc.
  • Each channel is the user's interface — no separate admin UI required

IDE Integration

None natively. Claude Code is used for:

  • Running skills during setup
  • Error recovery during nanoclaw.sh install
  • Fork customization (/customize)
  • Debugging (/debug)

Observability

  • scripts/q.ts — SQLite query helper for inspecting live state
  • Verbose mode on claw CLI (-v): shows commands, redacted payloads, exit codes
  • Session ID system for tracking and resuming conversations
  • No structured audit log format; relies on SQLite tables for operational state

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.