NanoClaw - Agentic CLI and Container-Isolated Personal AI Assistants

NanoClaw sits in the same broad family as OpenClaw and Hermes Agent, but it is more opinionated about size and isolation.

The short version: it is a personal AI assistant runtime where agents run inside containers, messages move through SQLite inbox/outbox files, and the system is intended to be small enough that you can audit and customize it.

The more interesting current angle is that NanoClaw is not only a messenger bot. It also has an agentic CLI story.

NanoClaw is a lightweight personal AI assistant runtime with container-isolated agents, a local admin CLI, and a terminal path for running agents without a chat app.

NanoClaw GitHub Source Code NanoClaw Website NanoClaw Documentation NanoClaw CLI Documentation License: MIT

What is NanoClaw?

NanoClaw is a self-hostable AI assistant runtime built around Claude Code and Anthropic’s Claude Agent SDK.

The project started as a lightweight way to run a Claude-powered personal assistant from chat surfaces like WhatsApp. NanoClaw v2 is broader: multiple agent groups, multiple channels, scheduled tasks, agent-to-agent routing, and per-session containers.

The project’s pitch is different from “configure a big framework”:

• keep the core small
• run agents in containers
• avoid raw credentials inside agent containers
• install channels and providers as skills
• customize behavior by editing the source code

That last point is important. NanoClaw is intentionally code-first. If you want a different trigger word, response style, custom channel, or provider path, the intended workflow is often: ask Claude Code to modify your NanoClaw fork.

The Agentic CLI Angle

There are two CLI surfaces worth separating.

ncl: Admin CLI

The repository ships bin/ncl, which launches:

pnpm exec tsx src/cli/client.ts "$@"

This is NanoClaw’s admin CLI. It talks to the running host process over a Unix socket:

data/ncl.sock

Examples:

ncl groups list
ncl groups get <id>
ncl groups config get <id>
ncl groups restart <id> --rebuild
ncl sessions list
ncl approvals list

So ncl is not a simple standalone binary. It is a control surface for a running NanoClaw host.

claw: Terminal Agent CLI

The public docs also describe a separate claw CLI installed by the /claw Claude Code skill.

That one is more like the agentic CLI people expect:

claw "What's on my calendar today?"
claw -g dev "Review the latest deploy logs"
git diff main..HEAD | claw --pipe -g dev "Review this diff for issues"
claw --list-groups

The docs describe claw as a Python script that reads NanoClaw’s SQLite database and .env, resolves a target agent group, then runs an agent container with a JSON payload. That means you can use a NanoClaw agent from the terminal before or instead of wiring a chat app.

The practical distinction:

This is the post’s main clarification, because many summaries describe NanoClaw only as a WhatsApp/Telegram/Discord assistant.

How NanoClaw Works

The architecture is deliberately simple:

message source
  -> channel adapter or CLI
  -> Node host process
  -> central SQLite routing DB
  -> per-session inbound.db
  -> Bun agent-runner in an isolated container
  -> per-session outbound.db
  -> host delivery loop
  -> user/channel/CLI response

The system has a single host process. It handles channels, routing, services, scheduling, and container lifecycle.

Each active agent session gets a container. The host writes messages into inbound.db, and the container writes replies into outbound.db. Each SQLite file has exactly one writer, which avoids the usual cross-mount SQLite locking problem.

Important source paths:

Security Model

NanoClaw’s core security claim is isolation, not allowlists.

Agents run in containers and can only see explicitly mounted directories. The host remains the trusted orchestrator; incoming chat messages are untrusted; agent containers are sandboxed execution environments.

Credentials are handled through OneCLI Agent Vault :

1. Real credentials live in OneCLI.
2. NanoClaw spawns containers with outbound requests routed through the OneCLI gateway.
3. OneCLI injects credentials at the HTTP layer based on destination and policy.
4. The agent container does not get raw API keys in files or environment variables.

This is still a personal automation system, so it deserves caution. But the security boundary is much clearer than giving a large single-process assistant broad host access.

Trying NanoClaw Locally

I tested the current source checkout locally rather than only relying on the older draft notes.

The checkout:

tmp/foss-post/nanoclaw

Observed upstream state:

The version detail matters: the current package version is ahead of the latest tag/changelog entry I saw locally. If you are following releases, check both package.json and git tags.

Host Install

The machine did not have pnpm initially, so I used Corepack:

corepack enable
corepack prepare [email protected] --activate
pnpm --version

Then:

/usr/bin/time -v pnpm install --frozen-lockfile

Result:

The install completed cleanly. It ran expected install steps for esbuild and better-sqlite3.

Typecheck and Tests

Typecheck:

/usr/bin/time -v pnpm run typecheck

Result:

Tests:

/usr/bin/time -v pnpm test

Result:

The test output is noisy because it exercises migrations, routing, sessions, and agent-to-agent messaging, but the result was clean.

CLI Behavior Without the Host

The local admin CLI help worked:

./bin/ncl --help

Output:

Usage: ncl <resource> <verb> [target] [--key value ...] [--json]

Run `ncl help` to list available resources and commands.

Running a real command without the daemon failed as expected:

./bin/ncl help

It reported:

ncl: cannot reach NanoClaw host (connect ENOENT .../data/ncl.sock).
Is the host running? Start it with: pnpm run dev

That is a useful field note: ncl is a host-control CLI, not a self-contained offline inspector.

What I Did Not Run

I did not run the full bash nanoclaw.sh installer unattended.

That script can:

• install or reuse OneCLI
• register credentials
• build the full agent container image
• pair a first channel or local CLI agent
• configure a system service
• hand off to Claude Code for recovery

Those are appropriate setup steps for a real personal assistant, but they are not safe to run blindly during a blog-post smoke test.

I also did not build the full agent container in this pass. The Dockerfile installs Chromium, Bun, Claude Code, agent-browser, Vercel CLI, and browser/runtime dependencies. That is a heavier operation than the host TypeScript checks, especially on a machine with no swap.

Does NanoClaw Need Docker Compose?

No, not in the usual self-hosted app sense.

NanoClaw uses containers, but it does not ship as a normal docker-compose.yml application where you pull nanoclaw/nanoclaw:latest and expose a web port.

The project builds an agent container image locally from your checkout:

./container/build.sh

That image is tied to your fork, installed skills, providers, packages, MCP servers, and mounts. Because of that, I did not add a Home-Lab Docker Compose file for this post.

When I Would Use It

NanoClaw makes sense if you want:

• a personal assistant that can live in chat channels
• terminal access to agents through claw
• admin control through ncl
• container isolation by default
• a small codebase you can inspect
• Claude Code-driven customization
• scheduled personal workflows
• agents that can coordinate through the same message model

It is less ideal if you want:

• a simple hosted web UI
• a one-command Docker Compose stack
• a pure local-model-first assistant
• a config-file-driven framework
• a system you never intend to modify

Useful Commands

Clone and start full setup:

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash nanoclaw.sh

Lightweight validation:

corepack enable
corepack prepare [email protected] --activate
pnpm install --frozen-lockfile
pnpm run typecheck
pnpm test

Admin CLI:

./bin/ncl --help
./bin/ncl groups list
./bin/ncl sessions list
./bin/ncl approvals list

Agent container build:

./container/build.sh

Terminal agent CLI after installing /claw:

claw --list-groups
claw "Hello from the terminal"
git diff main..HEAD | claw --pipe -g dev "Review this diff"

NanoClaw vs OpenClaw vs Hermes

The personal-assistant part of this series has three useful shapes:

Pick NanoClaw when isolation and code-level customization matter more than a large built-in control plane.

FAQ

ncl  = admin/control CLI for the running host
claw = terminal prompt CLI installed by the /claw skill