Claude Skill MartBrowse skillsWhat is a Skill?
 
← Back to list

NanoClaw Container Debug

A step-by-step debugging playbook for NanoClaw's containerized agent runtime — logs, session DBs, mounts and auth failures.

Dev & CodingAdvanced★ 30,471⑂ 12,865AI score 7/10Last updated: Aug 9, 2026

What it does

This skill is a dedicated troubleshooting guide for NanoClaw's container-based agent execution system. It explains the two-session-DB model (inbound.db, outbound.db) that is the only IO surface between the Node host and the Bun container, and shows how to pinpoint exactly where a message flow broke with a few SQL queries.

  • Architecture diagram plus the expected mount targets (/workspace, /home/node/.claude, /app/src)
  • Log-location table (host errors, app log, setup logs) and how to enable LOG_LEVEL=debug
  • Four common failure modes: silent message loss from duplicate service instances, containers exiting immediately, mount problems, and stale sessions detected via .heartbeat
  • Commands for restarting containers, rebuilding the image, clearing a session, plus a one-shot diagnostic script

Who it's for

  • Operators and contributors running or forking the NanoClaw project
  • Developers looking for a reference pattern for debugging container-isolated agent architectures
  • Engineers comfortable with Docker, systemd and SQLite inspection

Examples

  1. "The bot stopped replying" → the skill walks messages_in then messages_out to separate a routing failure from an agent failure from a delivery failure (including the null platform_message_id duplicate-instance bug).
  2. "An API returns 401" → it checks whether the OneCLI gateway agent is in selective secret mode and fixes it with onecli agents set-secret-mode --mode all.
  3. "A session is stuck processing" → it inspects the .heartbeat mtime to confirm the container died mid-run, then recovers with ncl groups restart.

· · · Install guide · · ·

Install in the Claude app (no terminal)
  1. Download the ZIP with the button below.
  2. In Claude, open Settings → Capabilities and turn on 'Code execution and file creation'. (one time)
  3. Go to Customize → Skills → + → 'Upload a skill' and upload the ZIP.
↓ Download ZIP
Install in Claude Code

Let Claude do it — paste this into Claude Code

Install the skill I found on Claude Skill Mart.
Copy the .claude/skills/debug folder from the GitHub repo nanocoai/nanoclaw into my ~/.claude/skills/debug/.
When it's done, tell me in one line what this skill can do.

Install with a command instead

git clone https://github.com/nanocoai/nanoclaw /tmp/nanoclaw && mkdir -p ~/.claude/skills/debug && cp -r /tmp/nanoclaw/.claude/skills/debug/* ~/.claude/skills/debug/

⚠ This is a third-party skill. Check the source repository before installing.

  1. Open a terminal and go to your working directory.
  2. Clone the repository: git clone https://github.com/nanocoai/nanoclaw
  3. Create the skill folder: mkdir -p ~/.claude/skills/debug
  4. Copy the files: cp -r nanoclaw/.claude/skills/debug/* ~/.claude/skills/debug/
  5. Restart Claude Code and say something like "the container isn't responding, debug it" to trigger the skill.
  6. The skill is most useful when run from inside a NanoClaw checkout — make sure Docker, pnpm and the ncl CLI are available.
  7. Commands such as rm -rf data/v2-sessions/... and systemctl --user stop are irreversible; double-check the path and service name before executing them.
View source on GitHub ↗License: MIT