627 lines
25 KiB
Markdown
627 lines
25 KiB
Markdown
# Clawdie Specification
|
|
|
|
A personal AI assistant accessible via messaging channels, with persistent memory per conversation, scheduled tasks, and integrations.
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Architecture](#architecture)
|
|
2. [Folder Structure](#folder-structure)
|
|
3. [Configuration](#configuration)
|
|
4. [Memory System](#memory-system)
|
|
5. [Session Management](#session-management)
|
|
6. [Message Flow](#message-flow)
|
|
7. [Commands](#commands)
|
|
8. [Scheduled Tasks](#scheduled-tasks)
|
|
9. [MCP Servers](#mcp-servers)
|
|
10. [Deployment](#deployment)
|
|
11. [Security Considerations](#security-considerations)
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ HOST (macOS) │
|
|
│ (Main Node.js Process) │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────────┐ ┌────────────────────┐ │
|
|
│ │ Telegram │────────────────────▶│ SQLite Database │ │
|
|
│ │ (grammy) │◀────────────────────│ (messages.db) │ │
|
|
│ └──────────────┘ store/send └─────────┬──────────┘ │
|
|
│ │ │
|
|
│ ┌────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────────────┐ ┌──────────────────┐ ┌───────────────┐ │
|
|
│ │ Message Loop │ │ Scheduler Loop │ │ IPC Watcher │ │
|
|
│ │ (polls SQLite) │ │ (checks tasks) │ │ (file-based) │ │
|
|
│ └────────┬─────────┘ └────────┬─────────┘ └───────────────┘ │
|
|
│ │ │ │
|
|
│ └───────────┬───────────┘ │
|
|
│ │ spawns jail │
|
|
│ ▼ │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ WARDEN RUNTIME (FREEBSD JAIL) │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ ┌──────────────────────────────────────────────────────────────┐ │
|
|
│ │ WARDEN WORKER │ │
|
|
│ │ │ │
|
|
│ │ Working directory: /workspace/group (mounted from host) │ │
|
|
│ │ Volume mounts: │ │
|
|
│ │ • groups/{name}/ → /workspace/group │ │
|
|
│ │ • groups/global/ → /workspace/global/ (non-main only) │ │
|
|
│ │ • data/sessions/{group}/.agent/ → /home/node/.agent/ │ │
|
|
│ │ • Additional dirs → /workspace/extra/* │ │
|
|
│ │ │ │
|
|
│ │ Tools (all groups): │ │
|
|
│ │ • Bash (safe - sandboxed in jail!) │ │
|
|
│ │ • Read, Write, Edit, Glob, Grep (file operations) │ │
|
|
│ │ • WebSearch, WebFetch (internet access) │ │
|
|
│ │ • agent-browser (browser automation) │ │
|
|
│ │ • mcp__nanoclaw__* (scheduler tools via IPC) │ │
|
|
│ │ │ │
|
|
│ └──────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Technology Stack
|
|
|
|
| Component | Technology | Purpose |
|
|
|-----------|------------|---------|
|
|
| Telegram Connection | Node.js (grammy) | Connect to Telegram, send/receive messages |
|
|
| Message Storage | SQLite (better-sqlite3) | Store messages for polling |
|
|
| Jail Runtime | FreeBSD jails | Isolated environments for agent execution |
|
|
| Warden Runtime | Clawdie execution layer | Project-specific name for jailed agent execution |
|
|
| Agent | `pi` / PI coding agent | Run the coding agent with tools and MCP servers |
|
|
| Browser Automation | agent-browser + Chromium | Web interaction and screenshots |
|
|
| Runtime | Node.js 20+ | Host process for routing and scheduling |
|
|
|
|
### Warden Naming
|
|
|
|
`Warden` is the Clawdie name for the isolated execution layer.
|
|
|
|
- **FreeBSD jail** remains the correct operating-system term
|
|
- **Bastille** remains the host-side jail manager
|
|
- **Warden runtime** refers to Clawdie's jailed execution model and worker dispatch
|
|
|
|
---
|
|
|
|
## Folder Structure
|
|
|
|
```
|
|
nanoclaw/
|
|
├── AGENTS.md # Project context for the coding agent
|
|
├── docs/
|
|
│ ├── SPEC.md # This specification document
|
|
│ ├── REQUIREMENTS.md # Architecture decisions
|
|
│ └── SECURITY.md # Security model
|
|
├── README.md # User documentation
|
|
├── package.json # Node.js dependencies
|
|
├── tsconfig.json # TypeScript configuration
|
|
├── .mcp.json # MCP server configuration (reference)
|
|
├── .gitignore
|
|
│
|
|
├── src/
|
|
│ ├── index.ts # Orchestrator: state, message loop, agent invocation
|
|
│ ├── channels/
|
|
│ │ └── telegram.ts # Telegram connection and send/receive
|
|
│ ├── ipc.ts # IPC watcher and task processing
|
|
│ ├── router.ts # Message formatting and outbound routing
|
|
│ ├── config.ts # Configuration constants
|
|
│ ├── types.ts # TypeScript interfaces (includes Channel)
|
|
│ ├── logger.ts # Pino logger setup
|
|
│ ├── db.ts # SQLite database initialization and queries
|
|
│ ├── group-queue.ts # Per-group queue with global concurrency limit
|
|
│ ├── mount-security.ts # Mount allowlist validation for jails
|
|
│ ├── telegram-auth.ts # Standalone Telegram token verification
|
|
│ ├── task-scheduler.ts # Runs scheduled tasks when due
|
|
│ └── jail-runner.ts # Spawns Warden workers in jails
|
|
│
|
|
├── jail/
|
|
│ ├── agent-runner/ # Code that runs inside the Warden jail worker
|
|
│ │ ├── package.json
|
|
│ │ ├── tsconfig.json
|
|
│ │ └── src/
|
|
│ │ ├── index.ts # Entry point (query loop, IPC polling, session resume)
|
|
│ │ └── ipc-mcp-stdio.ts # Stdio-based MCP server for host communication
|
|
│ └── skills/
|
|
│ └── agent-browser.md # Browser automation skill
|
|
│
|
|
├── dist/ # Compiled JavaScript (gitignored)
|
|
│
|
|
├── .agent/
|
|
│ └── skills/
|
|
│ ├── setup/SKILL.md # /setup - First-time installation
|
|
│ ├── customize/SKILL.md # /customize - Add capabilities
|
|
│ ├── debug/SKILL.md # /debug - Jail debugging
|
|
│ ├── add-telegram/SKILL.md # /add-telegram - Telegram channel
|
|
│ ├── add-gmail/SKILL.md # /add-gmail - Gmail integration
|
|
│ ├── add-voice-transcription/ # /add-voice-transcription - Whisper
|
|
│ ├── x-integration/SKILL.md # /x-integration - X/Twitter
|
|
│ └── add-parallel/SKILL.md # /add-parallel - Parallel agents
|
|
│
|
|
├── groups/
|
|
│ ├── AGENTS.md # Global memory (all groups read this)
|
|
│ ├── main/ # Self-chat (main control channel)
|
|
│ │ ├── AGENTS.md # Main channel memory
|
|
│ │ └── logs/ # Task execution logs
|
|
│ └── {Group Name}/ # Per-group folders (created on registration)
|
|
│ ├── AGENTS.md # Group-specific memory
|
|
│ ├── logs/ # Task logs for this group
|
|
│ └── *.md # Files created by the agent
|
|
│
|
|
├── store/ # Local data (gitignored)
|
|
│ ├── messages.db # SQLite database
|
|
│ └── messages.db # SQLite database (messages, chats, scheduled_tasks, task_run_logs, registered_groups, sessions, router_state)
|
|
│
|
|
├── data/ # Application state (gitignored)
|
|
│ ├── sessions/ # Per-group session data (.agent/ dirs with JSONL transcripts)
|
|
│ ├── env/env # Copy of .env for jail-side auth bootstrap
|
|
│ └── ipc/ # Jail IPC (messages/, tasks/)
|
|
│
|
|
├── logs/ # Runtime logs (gitignored)
|
|
│ ├── nanoclaw.log # Host stdout
|
|
│ └── nanoclaw.error.log # Host stderr
|
|
│ # Note: Per-jail logs are in groups/{folder}/logs/jail-*.log
|
|
│
|
|
└── launchd/
|
|
└── com.nanoclaw.plist # macOS service configuration
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Configuration constants are in `src/config.ts`:
|
|
|
|
```typescript
|
|
import path from 'path';
|
|
|
|
export const ASSISTANT_NAME = process.env.ASSISTANT_NAME || 'Andy';
|
|
export const POLL_INTERVAL = 2000;
|
|
export const SCHEDULER_POLL_INTERVAL = 60000;
|
|
|
|
// Paths are absolute (required for jail mounts)
|
|
const PROJECT_ROOT = process.cwd();
|
|
export const STORE_DIR = path.resolve(PROJECT_ROOT, 'store');
|
|
export const GROUPS_DIR = path.resolve(PROJECT_ROOT, 'groups');
|
|
export const DATA_DIR = path.resolve(PROJECT_ROOT, 'data');
|
|
|
|
// Jail configuration
|
|
export const JAIL_TIMEOUT = parseInt(process.env.JAIL_TIMEOUT || '1800000', 10); // 30min default
|
|
export const IPC_POLL_INTERVAL = 1000;
|
|
export const IDLE_TIMEOUT = parseInt(process.env.IDLE_TIMEOUT || '1800000', 10); // 30min — keep jail alive after last result
|
|
export const MAX_CONCURRENT_JAILS = Math.max(1, parseInt(process.env.MAX_CONCURRENT_JAILS || '5', 10) || 5);
|
|
|
|
export const TRIGGER_PATTERN = new RegExp(`^@${ASSISTANT_NAME}\\b`, 'i');
|
|
```
|
|
|
|
**Note:** Paths must be absolute for jail mounts to work correctly.
|
|
|
|
### Jail Configuration
|
|
|
|
Groups can have additional directories mounted via `jailConfig` in the SQLite `registered_groups` table (stored as JSON in the `jail_config` column). Example registration:
|
|
|
|
```typescript
|
|
registerGroup("1234567890@g.us", {
|
|
name: "Dev Team",
|
|
folder: "dev-team",
|
|
trigger: "@Andy",
|
|
added_at: new Date().toISOString(),
|
|
jailConfig: {
|
|
additionalMounts: [
|
|
{
|
|
hostPath: "~/projects/webapp",
|
|
jailPath: "webapp",
|
|
readonly: false,
|
|
},
|
|
],
|
|
timeout: 600000,
|
|
},
|
|
});
|
|
```
|
|
|
|
Additional mounts appear at `/workspace/extra/{jailPath}` inside the jail.
|
|
|
|
**Mount syntax note:** Read-write mounts use `-v host:container`, but readonly mounts require `--mount "type=bind,source=...,target=...,readonly"` (the `:ro` suffix may not work on all runtimes).
|
|
|
|
### Provider Authentication
|
|
|
|
Configure provider credentials in a `.env` file in the project root. Example:
|
|
|
|
```bash
|
|
OPENROUTER_API_KEY=sk-or-...
|
|
ANTHROPIC_API_KEY=sk-ant-api03-...
|
|
OPENAI_API_KEY=sk-...
|
|
```
|
|
|
|
Only the provider variables needed by the selected runtime are passed into the jail worker. This ensures unrelated environment variables in `.env` are not exposed to the agent.
|
|
|
|
### Changing the Assistant Name
|
|
|
|
Set the `ASSISTANT_NAME` environment variable:
|
|
|
|
```bash
|
|
ASSISTANT_NAME=Bot npm start
|
|
```
|
|
|
|
Or edit the default in `src/config.ts`. This changes:
|
|
- The trigger pattern (messages must start with `@YourName`)
|
|
- The response prefix (`YourName:` added automatically)
|
|
|
|
### Placeholder Values in launchd
|
|
|
|
Files with `{{PLACEHOLDER}}` values need to be configured:
|
|
- `{{PROJECT_ROOT}}` - Absolute path to your nanoclaw installation
|
|
- `{{NODE_PATH}}` - Path to node binary (detected via `which node`)
|
|
- `{{HOME}}` - User's home directory
|
|
|
|
---
|
|
|
|
## Memory System
|
|
|
|
Clawdie uses a hierarchical memory system based on AGENTS.md files.
|
|
|
|
### Memory Hierarchy
|
|
|
|
| Level | Location | Read By | Written By | Purpose |
|
|
|-------|----------|---------|------------|---------|
|
|
| **Global** | `groups/global/AGENTS.md` | All groups | Main only | Preferences, facts, context shared across all conversations |
|
|
| **Group** | `groups/{name}/AGENTS.md` | That group | That group | Group-specific context, conversation memory |
|
|
| **Files** | `groups/{name}/*.md` | That group | That group | Notes, research, documents created during conversation |
|
|
|
|
### How Memory Works
|
|
|
|
1. **Agent Context Loading**
|
|
- Agent runs with `cwd` set to `groups/{group-name}/`
|
|
- The agent runtime loads:
|
|
- `../global/AGENTS.md` or `/workspace/global/AGENTS.md` (global memory)
|
|
- `./AGENTS.md` (group memory)
|
|
|
|
2. **Writing Memory**
|
|
- When user says "remember this", agent writes to `./AGENTS.md`
|
|
- When user says "remember this globally" (main channel only), agent writes to the global `AGENTS.md`
|
|
- Agent can create files like `notes.md`, `research.md` in the group folder
|
|
|
|
3. **Main Channel Privileges**
|
|
- Only the "main" group (self-chat) can write to global memory
|
|
- Main can manage registered groups and schedule tasks for any group
|
|
- Main can configure additional directory mounts for any group
|
|
- All groups have Bash access (safe because it runs inside the jail)
|
|
|
|
---
|
|
|
|
## Session Management
|
|
|
|
Sessions enable conversation continuity - the agent remembers what you talked about.
|
|
|
|
### How Sessions Work
|
|
|
|
1. Each group has a session ID stored in SQLite (`sessions` table, keyed by `group_folder`)
|
|
2. Session ID is passed to the runtime's resume option
|
|
3. The agent continues the conversation with full context
|
|
4. Session transcripts are stored as JSONL files in `data/sessions/{group}/.agent/`
|
|
|
|
---
|
|
|
|
## Message Flow
|
|
|
|
### Incoming Message Flow
|
|
|
|
```
|
|
1. User sends a Telegram message
|
|
│
|
|
▼
|
|
2. Telegram bot receives the message via the Bot API
|
|
│
|
|
▼
|
|
3. Message stored in SQLite (store/messages.db)
|
|
│
|
|
▼
|
|
4. Message loop polls SQLite (every 2 seconds)
|
|
│
|
|
▼
|
|
5. Router checks:
|
|
├── Is chat_jid in registered groups (SQLite)? → No: ignore
|
|
└── Does message match trigger pattern? → No: store but don't process
|
|
│
|
|
▼
|
|
6. Router catches up conversation:
|
|
├── Fetch all messages since last agent interaction
|
|
├── Format with timestamp and sender name
|
|
└── Build prompt with full conversation context
|
|
│
|
|
▼
|
|
7. Router invokes the jail-side agent runtime:
|
|
├── cwd: groups/{group-name}/
|
|
├── prompt: conversation history + current message
|
|
├── resume: session_id (for continuity)
|
|
└── mcpServers: nanoclaw (scheduler)
|
|
│
|
|
▼
|
|
8. Agent processes message:
|
|
├── Reads AGENTS.md files for context
|
|
└── Uses tools as needed (search, email, etc.)
|
|
│
|
|
▼
|
|
9. Router prefixes response with assistant name and sends via the channel
|
|
│
|
|
▼
|
|
10. Router updates last agent timestamp and saves session ID
|
|
```
|
|
|
|
### Trigger Word Matching
|
|
|
|
Messages must start with the trigger pattern (default: `@Andy`):
|
|
- `@Andy what's the weather?` → ✅ Triggers Claude
|
|
- `@andy help me` → ✅ Triggers (case insensitive)
|
|
- `Hey @Andy` → ❌ Ignored (trigger not at start)
|
|
- `What's up?` → ❌ Ignored (no trigger)
|
|
|
|
### Conversation Catch-Up
|
|
|
|
When a triggered message arrives, the agent receives all messages since its last interaction in that chat. Each message is formatted with timestamp and sender name:
|
|
|
|
```
|
|
[Jan 31 2:32 PM] John: hey everyone, should we do pizza tonight?
|
|
[Jan 31 2:33 PM] Sarah: sounds good to me
|
|
[Jan 31 2:35 PM] John: @Andy what toppings do you recommend?
|
|
```
|
|
|
|
This allows the agent to understand the conversation context even if it wasn't mentioned in every message.
|
|
|
|
---
|
|
|
|
## Commands
|
|
|
|
### Commands Available in Any Group
|
|
|
|
| Command | Example | Effect |
|
|
|---------|---------|--------|
|
|
| `@Assistant [message]` | `@Andy what's the weather?` | Talk to Claude |
|
|
|
|
### Commands Available in Main Channel Only
|
|
|
|
| Command | Example | Effect |
|
|
|---------|---------|--------|
|
|
| `@Assistant add group "Name"` | `@Andy add group "Family Chat"` | Register a new group |
|
|
| `@Assistant remove group "Name"` | `@Andy remove group "Work Team"` | Unregister a group |
|
|
| `@Assistant list groups` | `@Andy list groups` | Show registered groups |
|
|
| `@Assistant remember [fact]` | `@Andy remember I prefer dark mode` | Add to global memory |
|
|
|
|
---
|
|
|
|
## Scheduled Tasks
|
|
|
|
NanoClaw has a built-in scheduler that runs tasks as full agents in their group's context.
|
|
|
|
### How Scheduling Works
|
|
|
|
1. **Group Context**: Tasks created in a group run with that group's working directory and memory
|
|
2. **Full Agent Capabilities**: Scheduled tasks have access to all tools (WebSearch, file operations, etc.)
|
|
3. **Optional Messaging**: Tasks can send messages to their group using the `send_message` tool, or complete silently
|
|
4. **Main Channel Privileges**: The main channel can schedule tasks for any group and view all tasks
|
|
|
|
### Schedule Types
|
|
|
|
| Type | Value Format | Example |
|
|
|------|--------------|---------|
|
|
| `cron` | Cron expression | `0 9 * * 1` (Mondays at 9am) |
|
|
| `interval` | Milliseconds | `3600000` (every hour) |
|
|
| `once` | ISO timestamp | `2024-12-25T09:00:00Z` |
|
|
|
|
### Creating a Task
|
|
|
|
```
|
|
User: @Andy remind me every Monday at 9am to review the weekly metrics
|
|
|
|
Claude: [calls mcp__nanoclaw__schedule_task]
|
|
{
|
|
"prompt": "Send a reminder to review weekly metrics. Be encouraging!",
|
|
"schedule_type": "cron",
|
|
"schedule_value": "0 9 * * 1"
|
|
}
|
|
|
|
Claude: Done! I'll remind you every Monday at 9am.
|
|
```
|
|
|
|
### One-Time Tasks
|
|
|
|
```
|
|
User: @Andy at 5pm today, send me a summary of today's emails
|
|
|
|
Claude: [calls mcp__nanoclaw__schedule_task]
|
|
{
|
|
"prompt": "Search for today's emails, summarize the important ones, and send the summary to the group.",
|
|
"schedule_type": "once",
|
|
"schedule_value": "2024-01-31T17:00:00Z"
|
|
}
|
|
```
|
|
|
|
### Managing Tasks
|
|
|
|
From any group:
|
|
- `@Andy list my scheduled tasks` - View tasks for this group
|
|
- `@Andy pause task [id]` - Pause a task
|
|
- `@Andy resume task [id]` - Resume a paused task
|
|
- `@Andy cancel task [id]` - Delete a task
|
|
|
|
From main channel:
|
|
- `@Andy list all tasks` - View tasks from all groups
|
|
- `@Andy schedule task for "Family Chat": [prompt]` - Schedule for another group
|
|
|
|
---
|
|
|
|
## MCP Servers
|
|
|
|
### NanoClaw MCP (built-in)
|
|
|
|
The `nanoclaw` MCP server is created dynamically per agent call with the current group's context.
|
|
|
|
**Available Tools:**
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| `schedule_task` | Schedule a recurring or one-time task |
|
|
| `list_tasks` | Show tasks (group's tasks, or all if main) |
|
|
| `get_task` | Get task details and run history |
|
|
| `update_task` | Modify task prompt or schedule |
|
|
| `pause_task` | Pause a task |
|
|
| `resume_task` | Resume a paused task |
|
|
| `cancel_task` | Delete a task |
|
|
| `send_message` | Send a message to the group |
|
|
|
|
---
|
|
|
|
## Deployment
|
|
|
|
NanoClaw runs as a single macOS launchd service.
|
|
|
|
### Startup Sequence
|
|
|
|
When NanoClaw starts, it:
|
|
1. **Ensures jail runtime is ready** - Checks jail tooling and reports stale jail artifacts from previous runs
|
|
2. Initializes the SQLite database (migrates from JSON files if they exist)
|
|
3. Loads state from SQLite (registered groups, sessions, router state)
|
|
4. Connects to Telegram:
|
|
- Starts the scheduler loop
|
|
- Starts the IPC watcher for jail messages
|
|
- Sets up the per-group queue with `processGroupMessages`
|
|
- Recovers any unprocessed messages from before shutdown
|
|
- Starts the message polling loop
|
|
|
|
### Service: com.nanoclaw
|
|
|
|
**launchd/com.nanoclaw.plist:**
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "...">
|
|
<plist version="1.0">
|
|
<dict>
|
|
<key>Label</key>
|
|
<string>com.nanoclaw</string>
|
|
<key>ProgramArguments</key>
|
|
<array>
|
|
<string>{{NODE_PATH}}</string>
|
|
<string>{{PROJECT_ROOT}}/dist/index.js</string>
|
|
</array>
|
|
<key>WorkingDirectory</key>
|
|
<string>{{PROJECT_ROOT}}</string>
|
|
<key>RunAtLoad</key>
|
|
<true/>
|
|
<key>KeepAlive</key>
|
|
<true/>
|
|
<key>EnvironmentVariables</key>
|
|
<dict>
|
|
<key>PATH</key>
|
|
<string>{{HOME}}/.local/bin:/usr/local/bin:/usr/bin:/bin</string>
|
|
<key>HOME</key>
|
|
<string>{{HOME}}</string>
|
|
<key>ASSISTANT_NAME</key>
|
|
<string>Andy</string>
|
|
</dict>
|
|
<key>StandardOutPath</key>
|
|
<string>{{PROJECT_ROOT}}/logs/nanoclaw.log</string>
|
|
<key>StandardErrorPath</key>
|
|
<string>{{PROJECT_ROOT}}/logs/nanoclaw.error.log</string>
|
|
</dict>
|
|
</plist>
|
|
```
|
|
|
|
### Managing the Service
|
|
|
|
```bash
|
|
# Install service
|
|
cp launchd/com.nanoclaw.plist ~/Library/LaunchAgents/
|
|
|
|
# Start service
|
|
launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
|
|
|
|
# Stop service
|
|
launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
|
|
|
|
# Check status
|
|
launchctl list | grep nanoclaw
|
|
|
|
# View logs
|
|
tail -f logs/nanoclaw.log
|
|
```
|
|
|
|
---
|
|
|
|
## Security Considerations
|
|
|
|
### Jail Isolation
|
|
|
|
All agents run inside containers (lightweight Linux VMs), providing:
|
|
- **Filesystem isolation**: Agents can only access mounted directories
|
|
- **Safe Bash access**: Commands run inside the jail, not on the host
|
|
- **Network isolation**: Can be configured per-jail if needed
|
|
- **Process isolation**: Container processes can't affect the host
|
|
- **Non-root user**: Container runs as unprivileged `node` user (uid 1000)
|
|
|
|
### Prompt Injection Risk
|
|
|
|
Incoming channel messages could contain malicious instructions attempting to manipulate the agent's behavior.
|
|
|
|
**Mitigations:**
|
|
- Jail isolation limits blast radius
|
|
- Only registered groups are processed
|
|
- Trigger word required (reduces accidental processing)
|
|
- Agents can only access their group's mounted directories
|
|
- Main can configure additional directories per group
|
|
- Claude's built-in safety training
|
|
|
|
**Recommendations:**
|
|
- Only register trusted groups
|
|
- Review additional directory mounts carefully
|
|
- Review scheduled tasks periodically
|
|
- Monitor logs for unusual activity
|
|
|
|
### Credential Storage
|
|
|
|
| Credential | Storage Location | Notes |
|
|
|------------|------------------|-------|
|
|
| Claude CLI Auth | data/sessions/{group}/.agent/ | Per-group isolation, mounted to /home/node/.agent/ |
|
|
| Telegram Bot Token | `.env` | Verified via `setup/telegram-auth.ts` |
|
|
|
|
### File Permissions
|
|
|
|
The groups/ folder contains personal memory and should be protected:
|
|
```bash
|
|
chmod 700 groups/
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
| Issue | Cause | Solution |
|
|
|-------|-------|----------|
|
|
| No response to messages | Service not running | Check `launchctl list | grep nanoclaw` |
|
|
| "Agent process exited with code 1" | Jail runtime failed to start | Check logs; Clawdie reports jail startup failures in `logs/clawdie.log` |
|
|
| "Agent process exited with code 1" | Session mount path wrong | Ensure mount is to `/home/node/.agent/` not `/root/.agent/` |
|
|
| Session not continuing | Session ID not saved | Check SQLite: `sqlite3 store/messages.db "SELECT * FROM sessions"` |
|
|
| Session not continuing | Mount path mismatch | Container user is `node` with HOME=/home/node; sessions must be at `/home/node/.agent/` |
|
|
| "TELEGRAM_BOT_TOKEN is not set" | Telegram bot token missing | Set `TELEGRAM_BOT_TOKEN` in `.env` and restart |
|
|
| "No groups registered" | Haven't added groups | Use `@Andy add group "Name"` in main |
|
|
|
|
### Log Location
|
|
|
|
- `logs/nanoclaw.log` - stdout
|
|
- `logs/nanoclaw.error.log` - stderr
|
|
|
|
### Debug Mode
|
|
|
|
Run manually for verbose output:
|
|
```bash
|
|
npm run dev
|
|
# or
|
|
node dist/index.js
|
|
```
|