NanoClaw Container Debugging

This guide covers debugging the containerized agent execution system.

Architecture Overview

Host (macOS)                          Container (Linux VM)
─────────────────────────────────────────────────────────────
src/container-runner.ts               container/agent-runner/
    │                                      │
    │ spawns container                      │ runs Claude Agent SDK
    │ with volume mounts                   │ with MCP servers
    │                                      │
    ├── data/env/env ──────────────> /workspace/env-dir/env
    ├── groups/{folder} ───────────> /workspace/group
    ├── data/ipc/{folder} ────────> /workspace/ipc
    ├── data/sessions/{folder}/.claude/ ──> /home/node/.claude/ (isolated per-group)
    └── (main only) project root ──> /workspace/project

Important: The container runs as user node with HOME=/home/node. Session files must be mounted to /home/node/.claude/ (not /root/.claude/) for session resumption to work.

Log Locations

Enabling Debug Logging

Set LOG_LEVEL=debug for verbose output:

bash
1# For development
2LOG_LEVEL=debug npm run dev
3
4# For launchd service (macOS), add to plist EnvironmentVariables:
5<key>LOG_LEVEL</key>
6<string>debug</string>
7# For systemd service (Linux), add to unit [Service] section:
8# Environment=LOG_LEVEL=debug

Debug level shows:

• Full mount configurations
• Container command arguments
• Real-time container stderr

Common Issues

1. "Claude Code process exited with code 1"

Check the container log file in groups/{folder}/logs/container-*.log

Common causes:

Missing Authentication

Invalid API key · Please run /login

Fix: Ensure .env file exists with either OAuth token or API key:

bash
1cat .env  # Should show one of:
2# CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...  (subscription)
3# ANTHROPIC_API_KEY=sk-ant-api03-...        (pay-per-use)

Root User Restriction

--dangerously-skip-permissions cannot be used with root/sudo privileges

Fix: Container must run as non-root user. Check Dockerfile has USER node.

2. Environment Variables Not Passing

Runtime note: Environment variables passed via -e may be lost when using -i (interactive/piped stdin).

Workaround: The system extracts only authentication variables (CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY) from .env and mounts them for sourcing inside the container. Other env vars are not exposed.

To verify env vars are reaching the container:

bash
1echo '{}' | docker run -i \
2  -v $(pwd)/data/env:/workspace/env-dir:ro \
3  --entrypoint /bin/bash nanoclaw-agent:latest \
4  -c 'export $(cat /workspace/env-dir/env | xargs); echo "OAuth: ${#CLAUDE_CODE_OAUTH_TOKEN} chars, API: ${#ANTHROPIC_API_KEY} chars"'

3. Mount Issues

Container mount notes:

• Docker supports both -v and --mount syntax
• Use :ro suffix for readonly mounts:

  bash
  1# Readonly
  2-v /path:/container/path:ro
  3
  4# Read-write
  5-v /path:/container/path

To check what's mounted inside a container:

bash
1docker run --rm --entrypoint /bin/bash nanoclaw-agent:latest -c 'ls -la /workspace/'

Expected structure:

/workspace/
├── env-dir/env           # Environment file (CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY)
├── group/                # Current group folder (cwd)
├── project/              # Project root (main channel only)
├── global/               # Global CLAUDE.md (non-main only)
├── ipc/                  # Inter-process communication
│   ├── messages/         # Outgoing WhatsApp messages
│   ├── tasks/            # Scheduled task commands
│   ├── current_tasks.json    # Read-only: scheduled tasks visible to this group
│   └── available_groups.json # Read-only: WhatsApp groups for activation (main only)
└── extra/                # Additional custom mounts

4. Permission Issues

The container runs as user node (uid 1000). Check ownership:

bash
1docker run --rm --entrypoint /bin/bash nanoclaw-agent:latest -c '
2  whoami
3  ls -la /workspace/
4  ls -la /app/
5'

All of /workspace/ and /app/ should be owned by node.

5. Session Not Resuming / "Claude Code process exited with code 1"

If sessions aren't being resumed (new session ID every time), or Claude Code exits with code 1 when resuming:

Root cause: The SDK looks for sessions at $HOME/.claude/projects/. Inside the container, HOME=/home/node, so it looks at /home/node/.claude/projects/.

Check the mount path:

bash
1# In container-runner.ts, verify mount is to /home/node/.claude/, NOT /root/.claude/
2grep -A3 "Claude sessions" src/container-runner.ts

Verify sessions are accessible:

bash
1docker run --rm --entrypoint /bin/bash \
2  -v ~/.claude:/home/node/.claude \
3  nanoclaw-agent:latest -c '
4echo "HOME=$HOME"
5ls -la $HOME/.claude/projects/ 2>&1 | head -5
6'

Fix: Ensure container-runner.ts mounts to /home/node/.claude/:

typescript
1mounts.push({
2  hostPath: claudeDir,
3  containerPath: '/home/node/.claude',  // NOT /root/.claude
4  readonly: false
5});

6. MCP Server Failures

If an MCP server fails to start, the agent may exit. Check the container logs for MCP initialization errors.

Manual Container Testing

Test the full agent flow:

bash
1# Set up env file
2mkdir -p data/env groups/test
3cp .env data/env/env
4
5# Run test query
6echo '{"prompt":"What is 2+2?","groupFolder":"test","chatJid":"test@g.us","isMain":false}' | \
7  docker run -i \
8  -v $(pwd)/data/env:/workspace/env-dir:ro \
9  -v $(pwd)/groups/test:/workspace/group \
10  -v $(pwd)/data/ipc:/workspace/ipc \
11  nanoclaw-agent:latest

Test Claude Code directly:

bash
1docker run --rm --entrypoint /bin/bash \
2  -v $(pwd)/data/env:/workspace/env-dir:ro \
3  nanoclaw-agent:latest -c '
4  export $(cat /workspace/env-dir/env | xargs)
5  claude -p "Say hello" --dangerously-skip-permissions --allowedTools ""
6'

Interactive shell in container:

bash
1docker run --rm -it --entrypoint /bin/bash nanoclaw-agent:latest

SDK Options Reference

The agent-runner uses these Claude Agent SDK options:

typescript
1query({
2  prompt: input.prompt,
3  options: {
4    cwd: '/workspace/group',
5    allowedTools: ['Bash', 'Read', 'Write', ...],
6    permissionMode: 'bypassPermissions',
7    allowDangerouslySkipPermissions: true,  // Required with bypassPermissions
8    settingSources: ['project'],
9    mcpServers: { ... }
10  }
11})

Important: allowDangerouslySkipPermissions: true is required when using permissionMode: 'bypassPermissions'. Without it, Claude Code exits with code 1.

Rebuilding After Changes

bash
1# Rebuild main app
2npm run build
3
4# Rebuild container (use --no-cache for clean rebuild)
5./container/build.sh
6
7# Or force full rebuild
8docker builder prune -af
9./container/build.sh

Checking Container Image

bash
1# List images
2docker images
3
4# Check what's in the image
5docker run --rm --entrypoint /bin/bash nanoclaw-agent:latest -c '
6  echo "=== Node version ==="
7  node --version
8
9  echo "=== Claude Code version ==="
10  claude --version
11
12  echo "=== Installed packages ==="
13  ls /app/node_modules/
14'

Session Persistence

Claude sessions are stored per-group in data/sessions/{group}/.claude/ for security isolation. Each group has its own session directory, preventing cross-group access to conversation history.

Critical: The mount path must match the container user's HOME directory:

• Container user: node
• Container HOME: /home/node
• Mount target: /home/node/.claude/ (NOT /root/.claude/)

To clear sessions:

bash
1# Clear all sessions for all groups
2rm -rf data/sessions/
3
4# Clear sessions for a specific group
5rm -rf data/sessions/{groupFolder}/.claude/
6
7# Also clear the session ID from NanoClaw's tracking (stored in SQLite)
8sqlite3 store/messages.db "DELETE FROM sessions WHERE group_folder = '{groupFolder}'"

To verify session resumption is working, check the logs for the same session ID across messages:

bash
1grep "Session initialized" logs/nanoclaw.log | tail -5
2# Should show the SAME session ID for consecutive messages in the same group

IPC Debugging

The container communicates back to the host via files in /workspace/ipc/:

bash
1# Check pending messages
2ls -la data/ipc/messages/
3
4# Check pending task operations
5ls -la data/ipc/tasks/
6
7# Read a specific IPC file
8cat data/ipc/messages/*.json
9
10# Check available groups (main channel only)
11cat data/ipc/main/available_groups.json
12
13# Check current tasks snapshot
14cat data/ipc/{groupFolder}/current_tasks.json

IPC file types:

• messages/*.json - Agent writes: outgoing WhatsApp messages
• tasks/*.json - Agent writes: task operations (schedule, pause, resume, cancel, refresh_groups)
• current_tasks.json - Host writes: read-only snapshot of scheduled tasks
• available_groups.json - Host writes: read-only list of WhatsApp groups (main only)

Quick Diagnostic Script

Run this to check common issues:

bash
1echo "=== Checking NanoClaw Container Setup ==="
2
3echo -e "\n1. Authentication configured?"
4[ -f .env ] && (grep -q "CLAUDE_CODE_OAUTH_TOKEN=sk-" .env || grep -q "ANTHROPIC_API_KEY=sk-" .env) && echo "OK" || echo "MISSING - add CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY to .env"
5
6echo -e "\n2. Env file copied for container?"
7[ -f data/env/env ] && echo "OK" || echo "MISSING - will be created on first run"
8
9echo -e "\n3. Container runtime running?"
10docker info &>/dev/null && echo "OK" || echo "NOT RUNNING - start Docker Desktop (macOS) or sudo systemctl start docker (Linux)"
11
12echo -e "\n4. Container image exists?"
13echo '{}' | docker run -i --entrypoint /bin/echo nanoclaw-agent:latest "OK" 2>/dev/null || echo "MISSING - run ./container/build.sh"
14
15echo -e "\n5. Session mount path correct?"
16grep -q "/home/node/.claude" src/container-runner.ts 2>/dev/null && echo "OK" || echo "WRONG - should mount to /home/node/.claude/, not /root/.claude/"
17
18echo -e "\n6. Groups directory?"
19ls -la groups/ 2>/dev/null || echo "MISSING - run setup"
20
21echo -e "\n7. Recent container logs?"
22ls -t groups/*/logs/container-*.log 2>/dev/null | head -3 || echo "No container logs yet"
23
24echo -e "\n8. Session continuity working?"
25SESSIONS=$(grep "Session initialized" logs/nanoclaw.log 2>/dev/null | tail -5 | awk '{print $NF}' | sort -u | wc -l)
26[ "$SESSIONS" -le 2 ] && echo "OK (recent sessions reusing IDs)" || echo "CHECK - multiple different session IDs, may indicate resumption issues"