NanoClaw

A personal Claude assistant secured by real containers: TypeScript/Node.js single-process orchestration, WhatsApp chat, SQLite memory, and scheduled jobs.

8.6kTypeScriptMIT

What is it?

NanoClaw is a personal AI assistant that is intentionally small enough to understand end-to-end. It places the agent inside real Linux containers so the trust boundary is OS isolation, not application-level permission toggles. Built with TypeScript and Node.js as a single-process orchestrator, it uses WhatsApp as the primary channel to drive chat triggers, scheduled jobs, tool execution, and memory writes in one tight loop. State and memory are local-first via SQLite for messages, groups, and sessions, while each group runs with its own isolated filesystem context. Setup is AI-native: Claude Code guides dependencies, auth, and container runtime wiring so you can self-host a private assistant on your own hardware.

Pain Points vs Innovation

✕Traditional Pain Points	✓Innovative Solutions
Running agents directly on the host makes it hard to be secure-by-default; a prompt mistake can touch real files and commands.	NanoClaw treats containers as the first security boundary—using Docker or Apple Container for filesystem isolation so tools run inside a controlled sandbox.
General-purpose assistants often grow into dependency-heavy systems that are difficult for one person to audit and customize.	A minimal single-process design keeps the message loop, scheduler, memory store, and container runner on the shortest path, while skills-based changes avoid bloating the core.

Architecture Deep Dive

Single-process message loop + per-group queues

A single Node process polls and routes inbound messages into per-group queues, then applies a global concurrency cap so execution is predictable and contexts do not cross-contaminate.

Containerized runner (OS-level isolation)

Agents and tools do not run on the host directly: only explicitly mounted directories are visible, and commands execute inside the container boundary provided by the runtime.

SQLite-backed state machine + memory store

Messages, groups, sessions, and runtime state are persisted in SQLite for resumability and durable context. Scheduled tasks add a second trigger path alongside chat-driven actions.

Deployment Guide

1. Prepare runtime (macOS/Linux, Node 20, and a container runtime)

bash

1node --version  # v20.x; docker --version  # Docker on macOS/Linux; Apple Container optional on macOS

2. Clone the repo

bash

1git clone https://github.com/qwibitai/nanoclaw.git && cd nanoclaw

3. Use Claude Code for guided setup and auth (deps + container wiring)

bash

1claude

4. Run the guided diagnostics flow

bash

1# Follow Claude Code prompts: setup / debug; verify WhatsApp connectivity and scheduler runs

Use Cases

Core Scene	Target Audience	Solution	Outcome
Security-first private WhatsApp assistant	individuals and indie builders	trigger summaries and automations via WhatsApp while tools run inside containers	self-hosted automation with a safer trust boundary
Group-isolated family/team helper	families or small teams	each group gets isolated memory and filesystem context plus scheduled briefings	long-running assistance without cross-group context leakage
Minimal, auditable ops automation agent	engineers offloading repetitive tasks	encode recurring workflows as scheduled jobs	controlled execution via readable code and container isolation

Limitations & Gotchas

It depends on specific tooling: Node 20, Claude Code, and Docker/Apple Container; constrained environments must provision these first.
It is built for one user, not as a general framework; new channels/features are intended to be added via skills on your fork.

Frequently Asked Questions

Why containers instead of host-level permission checks?▾

NanoClaw uses containers as the trust boundary: commands run in isolated processes and only explicitly mounted directories are visible. This is closer to OS-level least privilege than app-only allowlists.

How does the WhatsApp channel work?▾

It relies on the WhatsApp Web ecosystem; a common approach is using libraries like Baileys to manage sessions and send/receive messages in a polling loop. You can swap the channel in your fork.

How do memory and scheduled jobs avoid cross-talk?▾

Each group has its own directory and memory file; inbound messages are queued per group with a global concurrency cap. State is persisted locally so restarts can resume per-group execution cleanly.

What is it?

Pain Points vs Innovation

✕Traditional Pain Points	✓Innovative Solutions
Running agents directly on the host makes it hard to be secure-by-default; a prompt mistake can touch real files and commands.	NanoClaw treats containers as the first security boundary—using Docker or Apple Container for filesystem isolation so tools run inside a controlled sandbox.
General-purpose assistants often grow into dependency-heavy systems that are difficult for one person to audit and customize.	A minimal single-process design keeps the message loop, scheduler, memory store, and container runner on the shortest path, while skills-based changes avoid bloating the core.

Architecture Deep Dive

Single-process message loop + per-group queues

A single Node process polls and routes inbound messages into per-group queues, then applies a global concurrency cap so execution is predictable and contexts do not cross-contaminate.

Containerized runner (OS-level isolation)

Agents and tools do not run on the host directly: only explicitly mounted directories are visible, and commands execute inside the container boundary provided by the runtime.

SQLite-backed state machine + memory store

Messages, groups, sessions, and runtime state are persisted in SQLite for resumability and durable context. Scheduled tasks add a second trigger path alongside chat-driven actions.

Deployment Guide

1. Prepare runtime (macOS/Linux, Node 20, and a container runtime)

bash

1node --version  # v20.x; docker --version  # Docker on macOS/Linux; Apple Container optional on macOS

2. Clone the repo

bash

1git clone https://github.com/qwibitai/nanoclaw.git && cd nanoclaw

3. Use Claude Code for guided setup and auth (deps + container wiring)

bash

1claude

4. Run the guided diagnostics flow

bash

1# Follow Claude Code prompts: setup / debug; verify WhatsApp connectivity and scheduler runs

Use Cases

Core Scene	Target Audience	Solution	Outcome
Security-first private WhatsApp assistant	individuals and indie builders	trigger summaries and automations via WhatsApp while tools run inside containers	self-hosted automation with a safer trust boundary
Group-isolated family/team helper	families or small teams	each group gets isolated memory and filesystem context plus scheduled briefings	long-running assistance without cross-group context leakage
Minimal, auditable ops automation agent	engineers offloading repetitive tasks	encode recurring workflows as scheduled jobs	controlled execution via readable code and container isolation

Frequently Asked Questions

Why containers instead of host-level permission checks?▾

How does the WhatsApp channel work?▾

It relies on the WhatsApp Web ecosystem; a common approach is using libraries like Baileys to manage sessions and send/receive messages in a polling loop. You can swap the channel in your fork.

How do memory and scheduled jobs avoid cross-talk?▾

Each group has its own directory and memory file; inbound messages are queued per group with a global concurrency cap. State is persisted locally so restarts can resume per-group execution cleanly.