tanmay/Regolith
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ef24c4541372a5e59452582d95c508bc0cefee09
Regolith/REQUIREMENTS.md
gavrielc 09c0e8142e Add containerized agent execution with Apple Container 
- Agents run in isolated Linux VMs via Apple Container
- All groups get Bash access (safe - sandboxed in container)
- Browser automation via agent-browser + Chromium
- Per-group configurable additional directory mounts
- File-based IPC for messages and scheduled tasks
- Container image with Node.js 22, Chromium, agent-browser

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-31 22:55:57 +02:00

5.0 KiB
Raw Blame History

NanoClaw Requirements

Original requirements and design decisions from the project creator.

Vision

A personal Claude assistant accessible via WhatsApp, with minimal custom code.

Core components:

  • Claude Agent SDK as the core agent
  • Apple Container for isolated agent execution (Linux VMs)
  • WhatsApp as the primary I/O channel
  • Persistent memory per conversation and globally
  • Scheduled tasks that run Claude and can message back
  • Web access for search and browsing
  • Browser automation via agent-browser

Design philosophy:

  • Leverage existing tools (WhatsApp connector, Claude Agent SDK, MCP servers)
  • Minimal glue code
  • File-based systems where possible (CLAUDE.md for memory, folders for groups)

Architecture Decisions

Message Routing

  • A router listens to WhatsApp and routes messages based on configuration
  • Only messages from registered groups are processed
  • Trigger: @Andy prefix (case insensitive), configurable via ASSISTANT_NAME env var
  • Unregistered groups are ignored completely

Memory System

  • Per-group memory: Each group has a folder with its own CLAUDE.md
  • Global memory: Root CLAUDE.md is read by all groups, but only writable from "main" (self-chat)
  • Files: Groups can create/read files in their folder and reference them
  • Agent runs in the group's folder, automatically inherits both CLAUDE.md files

Session Management

  • Each group maintains a conversation session (via Claude Agent SDK)
  • /clear command resets the session but keeps memory files
  • Old session IDs are archived to a file

Container Isolation

  • All agents run inside Apple Container (lightweight Linux VMs)
  • Each agent invocation spawns a container with mounted directories
  • Containers provide filesystem isolation - agents can only see mounted paths
  • Bash access is safe because commands run inside the container, not on the host
  • Browser automation via agent-browser with Chromium in the container

Scheduled Tasks

  • Users can ask Claude to schedule recurring or one-time tasks from any group
  • Tasks run as full agents in the context of the group that created them
  • Tasks have access to all tools including Bash (safe in container)
  • Tasks can optionally send messages to their group via send_message tool, or complete silently
  • Task runs are logged to the database with duration and result
  • Schedule types: cron expressions, intervals (ms), or one-time (ISO timestamp)
  • From main: can schedule tasks for any group, view/manage all tasks
  • From other groups: can only manage that group's tasks

Group Management

  • New groups are added explicitly via the main channel
  • Groups are registered by editing data/registered_groups.json
  • Each group gets a dedicated folder under groups/
  • Groups can have additional directories mounted via containerConfig

Main Channel Privileges

  • Main channel is the admin/control group (typically self-chat)
  • Can write to global memory (groups/CLAUDE.md)
  • Can schedule tasks for any group
  • Can view and manage tasks from all groups
  • Can configure additional directory mounts for any group

Integration Points

WhatsApp

  • Using baileys library for WhatsApp Web connection
  • Messages stored in SQLite, polled by router
  • QR code authentication during setup

Email (Gmail)

  • Read-only MCP integration (can read and send, but not an I/O channel)
  • Optional, enabled during setup

Scheduler

  • Built-in scheduler runs on the host, spawns containers for task execution
  • Custom nanoclaw MCP server (inside container) provides scheduling tools
  • Tools: schedule_task, list_tasks, pause_task, resume_task, cancel_task, send_message
  • Tasks stored in SQLite with run history
  • Scheduler loop checks for due tasks every minute
  • Tasks execute Claude Agent SDK in containerized group context

Web Access

  • Built-in WebSearch and WebFetch tools
  • Standard Claude Agent SDK capabilities

Browser Automation

  • agent-browser CLI with Chromium in container
  • Snapshot-based interaction with element references (@e1, @e2, etc.)
  • Screenshots, PDFs, video recording
  • Authentication state persistence

Setup & Customization

Philosophy

  • Minimal configuration files
  • Setup and customization done via Claude Code
  • Users clone the repo and run Claude Code to configure
  • Each user gets a custom setup matching their exact needs

Skills

  • /setup - Install dependencies, authenticate WhatsApp/Gmail, configure scheduler, start services
  • /customize - General-purpose skill for adding capabilities (new channels like Telegram, new integrations, behavior changes)

Deployment

  • Runs on local Mac via launchd
  • Single Node.js process handles everything

Personal Configuration (Reference)

These are the creator's settings, stored here for reference:

  • Trigger: @Andy (case insensitive)
  • Response prefix: Andy:
  • Persona: Default Claude (no custom personality)
  • Gmail: Enabled
  • Main channel: Self-chat (messaging yourself in WhatsApp)

Project Name

NanoClaw - A reference to Clawdbot (now OpenClaw).

Reference in New Issue View Git Blame Copy Permalink