# Debug

Debug container agent issues.

- Repository: https://github.com/nanocoai/nanoclaw (31069 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add nanocoai/nanoclaw --skill debug -g -a claude-code -y`
Codex: `npx skills add nanocoai/nanoclaw --skill debug -g -a codex -y`
Cursor: `npx skills add nanocoai/nanoclaw --skill debug -g -a cursor -y`
Gemini CLI: `npx skills add nanocoai/nanoclaw --skill debug -g -a gemini-cli -y`

## Description

Debug container agent issues. Use when things aren't working, container fails, authentication problems, or to understand how the container system works. Covers logs, session DBs, mounts, and common issues.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# NanoClaw Container Debugging

This guide covers debugging the containerized agent execution system.

## Architecture Overview

The host is a single Node process that orchestrates per-session agent containers. The two session DBs are the **sole** IO surface between host and container, there is no IPC, no file watcher, and no stdin piping.

```
Host (Node)                                Container (Bun, Linux VM)
──────────────────────────────────────────────────────────────────────
src/container-runner.ts                    container/agent-runner/src/
    │                                          │
    │ spawns one container per session          │ polls inbound.db for work,
    │ with the session folder mounted          │ calls the agent provider,
    │ at /workspace                            │ writes replies to outbound.db
    │                                          │
    ├── data/v2-sessions/<group>/<session>/ ──> /workspace
    │     ├── inbound.db   (host writes, container reads RO)
    │     ├── outbound.db  (container writes, host reads)
    │     └── .heartbeat   (container touches → /workspace/.heartbeat)
    ├── groups/<folder> ─────────────────────> /workspace/agent  (cwd)
    ├── <group>/.claude-shared ──────────────> /home/node/.claude
    └── agent-runner src + skills ───────────> /app/src, /app/skills
```

**Message flow:** host writes a row to `inbound.db` (`messages_in`) and wakes the container; the container's poll loop picks it up, runs the agent, and writes the reply to `outbound.db` (`messages_out`); the host's delivery poll reads `messages_out` and sends it through the channel adapter. See [docs/db.md](../../../docs/db.md) and [docs/db-session.md](../../../docs/db-session.md) for the full two-DB model.

**Container identity:** the container runs as user `node` with `HOME=/home/node`. Per-group Claude state (settings, session history) lives in `<group>/.claude-shared` on the host, mounted to `/home/node/.claude`.

## Log Locations

The rest: https://github.com/nanocoai/nanoclaw/blob/HEAD/.claude/skills/debug/SKILL.md