Skip to main content
NanoClaw Pro uses a single-process architecture with container-isolated agent execution. This design provides simplicity, reliability, and security.

​
System Architecture

​
Core Components

​
Single Process Design

NanoClaw Pro runs as a single Node.js process that:
  • Manages all channel connections (WhatsApp, Telegram, Slack, Discord, Gmail)
  • Polls SQLite for new messages every 2 seconds
  • Routes messages to the appropriate container
  • Manages agent lifecycle and concurrency
  • Handles scheduled task execution
Benefits:
  • Simple deployment (one service, one process)
  • Easy to debug and monitor
  • No IPC complexity between services
  • Graceful shutdown handling
Location: src/index.ts:465-575

​
SQLite Storage

All persistent state is stored in a single SQLite database at store/messages.db:
TablePurpose
messagesMessage history for registered groups
chatsChat metadata (name, last activity)
registered_groupsGroup configuration and permissions
sessionsClaude session IDs for conversation continuity
scheduled_tasksTask definitions and schedules
task_run_logsTask execution history
router_stateMessage processing cursors
Why SQLite:
  • Zero configuration
  • Transactional integrity
  • Fast local queries
  • Embeddable (no separate database process)
  • Automatic backups via file copy
Location: src/db.ts:17-86
SQLite is perfect for single-machine deployments. NanoClaw Pro doesn’t need distributed databases or message queues.

​
Container Execution Model

Agents run in isolated Linux containers (lightweight VMs) spawned on-demand: 
// From src/container-runner.ts:258-306
const container = spawn(CONTAINER_RUNTIME_BIN, [
  'run', '-i', '--rm',
  '--name', containerName,
  '-v', `${groupDir}:/workspace/group`,
  '-v', `${sessionsDir}:/home/node/.claude`,
  '-v', `${ipcDir}:/workspace/ipc`,
  // ... additional mounts
  CONTAINER_IMAGE
]);
Container Lifecycle:
  1. Spawn - Container created when messages arrive for a group
  2. Execute - Agent processes messages with full Claude SDK capabilities
  3. Idle - Container stays alive after output (configurable timeout)
  4. Pipe - New messages piped to stdin while container is idle
  5. Terminate - Container exits after idle timeout or on error
Benefits:
  • Security: Filesystem and process isolation
  • Resource cleanup: Automatic with --rm flag
  • Fresh environment: No state pollution between runs
  • Safe Bash: Commands execute in container, not on host
Location: src/container-runner.ts:258-638

​
Technology Stack

ComponentTechnologyPurpose
Host ProcessNode.js 20+Main orchestrator
DatabaseSQLite (better-sqlite3)Persistent storage
Container RuntimeContainer (Linux VM)Agent isolation
Agent SDK@anthropic-ai/claude-agent-sdkClaude with tools
ChannelsSelf-registering modulesMulti-platform support
SchedulerCron parser + interval timerTask scheduling

​
Data Flow

​
Incoming Message Flow

​
Scheduled Task Flow

​
Deployment Model

NanoClaw Pro runs as a single system service:

​
macOS (launchd)

<!-- launchd/com.nanoclaw.plist -->
<key>Label</key>
<string>com.nanoclaw</string>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>

​
Linux (systemd)

# systemd/nanoclaw.service
[Unit]
Description=NanoClaw Personal Assistant

[Service]
Type=simple
ExecStart=/usr/bin/node /path/to/dist/index.js
Restart=always
Service Management: 
# macOS
launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
launchctl kickstart -k gui/$(id -u)/com.nanoclaw

# Linux
systemctl --user start nanoclaw
systemctl --user restart nanoclaw

​
Startup Sequence

When NanoClaw Pro starts:
  1. Container Runtime Check - Ensures runtime is running, kills orphaned containers
  2. Database Init - Creates schema, runs migrations from JSON files if needed
  3. Load State - Restores sessions, groups, and message cursors from SQLite
  4. Connect Channels - Instantiates configured channels, skips those without credentials
  5. Start Subsystems - Scheduler loop, IPC watcher, group queue processor
  6. Recover Messages - Re-processes any messages that arrived before shutdown
  7. Message Loop - Begins polling for new messages
Location: src/index.ts:465-575
NanoClaw Pro automatically recovers from crashes by re-processing unhandled messages from SQLite.

​
Concurrency Control

The GroupQueue manages container concurrency:
  • Global limit: Max 5 concurrent containers (configurable via MAX_CONCURRENT_CONTAINERS)
  • Per-group serialization: One container per group at a time
  • Message piping: New messages sent to active containers via stdin
  • Idle reuse: Containers stay alive 30 minutes after output
Why serialize per-group?
  • Prevents race conditions in group folder writes
  • Ensures conversation order
  • Simpler session management
Location: src/group-queue.ts

​
Next Steps

Message Flow

Deep dive into message routing and processing

Channel System

How channels self-register and integrate

Session Management

Conversation continuity and memory

Security

Container isolation and security model

Build docs developers (and LLMs) love

Get started for freeTalk to us