NanoClaw - Secure personal AI agent with container isolation

What is NanoClaw

NanoClaw addresses a fundamental technical pain point in the modern AI landscape: the overwhelming complexity of enterprise-grade agent frameworks. While powerful, frameworks like OpenClaw—with its 434,453 lines of code across thousands of files and 70+ dependencies—are effectively black boxes for individual developers and privacy-conscious users. They are difficult to audit, understand, and customize, creating a trust deficit for personal use cases.

NanoClaw is a minimalist, open-source personal AI agent designed from the ground up for transparency and user sovereignty. It is built on a radically simplified architecture: a single Node.js process comprising just 15 source files and approximately 3,900 lines of code. This is less than 1% the size of OpenClaw's codebase. Its core philosophy is to provide a fully auditable, comprehensible, and customizable AI assistant that runs on your own hardware.

Technically, NanoClaw leverages the Claude Agent SDK for its core AI capabilities but replaces application-level permission checks with real OS-level container isolation. Each agent session executes within an ephemeral Linux container (or Apple Container on macOS), providing true process, filesystem, and IPC namespace isolation. This architectural choice eliminates the need for complex microservices or message brokers, resulting in a dependency count of less than 10.

The project has gained significant traction in the developer community, evidenced by 25.3k+ GitHub Stars and 8.5k+ Forks, and has been featured in technical publications like VentureBeat, Fortune, and The New Stack. It is positioned not as a team collaboration platform but as a personal tool for developers, tech enthusiasts, and privacy-focused individuals who demand complete control over their AI interactions.

NanoClaw's Core Technical Features

NanoClaw's power lies in its deliberate technical choices, which prioritize security, simplicity, and extensibility over monolithic feature bloat.

Container Isolation Architecture The primary security boundary is a real container. On each invocation, a fresh, ephemeral container is spun up with the --rm flag. The container process runs as a non-privileged user (UID 1000), with strict filesystem isolation: only explicitly mounted directories from a user-managed allowlist are visible. This provides guaranteed isolation that application-level sandboxes cannot match.

Security Boundary & Mount Allowlist A critical security component is the mount allowlist, stored at ~/.config/nanoclaw/mount-allowlist.json. This file, which is never mounted into the container, defines which host directories an agent can access. By default, sensitive paths like .ssh, .aws, .kube, .docker, and files containing credentials or .env are blocked. The system performs symbolic link resolution to prevent path traversal attacks and validates all container paths before mounting.

Credential Proxy System API keys and other secrets never enter the container environment. Instead, the host runs a lightweight HTTP credential proxy that transparently injects authentication headers (like x-api-key) into outgoing requests from the container. The agent inside the container only sees placeholder keys, ensuring that even a compromised agent cannot exfiltrate real credentials.

Group Isolation Mechanism NanoClaw implements a multi-tenant architecture for personal use. Each chat group (e.g., family, work project) gets an isolated environment:

• Independent Memory: A separate CLAUDE.md file and Claude session stored in data/sessions/{group}/.claude/.
• Isolated Filesystem: Each group has its own mounted workspace.
• Separate Container Sandbox: IPC and process isolation between groups. This allows a single NanoClaw instance to serve multiple contexts without data leakage.

Agent Swarms Implementation NanoClaw is the first personal AI agent to support Agent Swarms. Using the /add-parallel skill, users can spawn multiple specialized agents to collaborate on complex tasks, enabling parallel analysis and division of labor previously seen only in enterprise frameworks.

Skill System Architecture To avoid codebase inflation, functionality is added via a git-based skill system. Skills are maintained as separate git branches (categorized as Feature, Utility, Operational, or Container skills). Users merge desired skills into their fork. This keeps the core lean while enabling endless customization, such as adding Telegram support or a PDF reader.

Technical Application Scenarios

NanoClaw excels in specific technical scenarios where its architecture provides distinct advantages over cloud-based or monolithic alternatives.

Privacy-Sensitive Task Processing For developers handling proprietary code, financial data, or personal information, sending data to a cloud AI API is a non-starter. NanoClaw's local execution combined with container isolation provides a dual guarantee: AI capabilities are applied locally, and the agent is confined to a sandbox. This is ideal for tasks like analyzing private logs, refactoring internal codebases, or summarizing confidential documents.

Fully Auditable AI Operations In regulated industries or for security researchers, understanding exactly what an AI system is doing is paramount. NanoClaw's entire codebase can be read and understood in under 8 minutes. This transparency allows for rigorous security audits, compliance verification, and the elimination of unexpected behaviors that plague larger, opaque frameworks.

Scheduled Automation with Cron-like Precision The built-in scheduler supports three trigger types: cron expressions, millisecond intervals, and one-time execution. It uses an atomic declaration mechanism to prevent duplicate execution of the same job. A practical example is automating a daily 9 AM digest of specific RSS feeds or GitHub notifications, with the AI summarizing and sending results back to a designated chat group.

Multi-Group Collaboration with Hard Isolation A developer can use a single NanoClaw instance for both a family group and an open-source project group. The family group's memory, file access, and AI conversations are completely isolated from the project group's. This allows for resource sharing while maintaining strict context and data separation, mimicking secure multi-tenancy on a personal scale.

Custom Extension via Natural Language The AI-native design extends to customization. Instead of writing code, users describe a need to Claude Code (e.g., "add a skill to fetch my calendar events"). Claude Code can directly modify the NanoClaw codebase to implement the feature. This dramatically lowers the barrier to creating a truly personalized AI assistant.

Multi-Channel Messaging Integration The channel system is self-registering and modular. Starting with WhatsApp Web support, adding Telegram involves running the /add-telegram skill. Channels operate in parallel, allowing the AI assistant to be available simultaneously on WhatsApp for quick queries and Slack for team coordination, with context maintained per group across channels.

Technical Architecture & Ecosystem

NanoClaw's architecture is defined by its conscious choice of a simple, modern tech stack and its position within a broader ecosystem of AI tools and runtimes.

Core Technology Stack

• Language: Primarily TypeScript (95.6%), with minor Python (2.7%) for specific utilities.
• Runtime: Node.js 20+.
• Agent SDK: @anthropic-ai/claude-agent-sdk (v0.2.29) for core AI interaction.
• Local Storage: SQLite via better-sqlite3 for lightweight, persistent message and state storage.
• Testing: Vitest for unit and integration tests.
• Container Runtimes: Docker (Linux/macOS) and Apple Container (macOS, optimized for Apple Silicon).

Third-Party Model & Service Integration While optimized for Claude, the architecture supports alternative AI backends. Users can configure endpoints for Ollama (local LLMs), Together AI, Fireworks, and other providers compatible with the Claude Agent SDK's interface, offering flexibility in model choice and cost management.

Community & Development Ecosystem The project is maintained by a core team led by @gavrielc and supported by an active community of 57 contributors with over 424 commits. Development is facilitated through:

• Discord Community: For real-time discussion and support.
• GitHub Discussions & Issues: For structured planning and bug tracking.
• Comprehensive Docs: Including SPEC.md (architecture) and SECURITY.md (security model).
• CI/CD Pipeline: Automated testing and quality checks.

Architectural Comparison: NanoClaw vs. OpenClaw

This comparison highlights NanoClaw's fundamental design divergence: it trades horizontal scalability for vertical simplicity and user trust.

Quick Start & Integration Guide

Getting started with NanoClaw involves a streamlined, AI-guided process that minimizes manual configuration.

System Requirements

• Operating System: macOS or Linux.
• Node.js: Version 20 or higher.
• Claude Code: An active Claude Code subscription (claude.ai/product/claude-code).
• Container Runtime:
  • macOS: Apple Container (recommended for Apple Silicon) or Docker Desktop.
  • Linux: Docker Engine.

Installation & AI-Native Setup

1. Clone the Repository: git clone https://github.com/qwibitai/nanoclaw.git && cd nanoclaw
2. Launch Claude Code in the project directory.
3. Run the Setup Skill: Within Claude Code, execute /setup. This interactive skill will:
   • Install Node.js dependencies.
   • Guide you through authenticating your chosen messaging channels (e.g., WhatsApp Web QR scan).
   • Detect and configure the available container runtime (Apple Container or Docker).
   • Start the necessary background services.
   • There are no configuration files to edit manually.

Minimal Viable Test Once setup completes, the agent is typically connected to WhatsApp. Simply send a message to the AI's number from your phone. You should receive an intelligent response, confirming the stack is operational.

Environment Configuration & Best Practices

• Mount Allowlist: Populate ~/.config/nanoclaw/mount-allowlist.json cautiously. Start with a single, non-critical project directory.
• Skill Management: Add skills incrementally. Use /add-telegram or browse the skill branches in the repository.
• Start with the Main Group: Perform initial testing and configuration in the trusted "Main Group" before creating additional groups.
• Monitoring: Use standard commands like docker ps or ps aux | grep node to monitor container and process health.

Frequently Asked Questions (FAQ)