debug
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.
Profile →npx skills add nanocoai/nanoclaw --skill debug --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# 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 con
- Architecture Overview
- Log Locations
- Enabling Debug Logging
- Inspecting Session DBs
- Common Issues
- 2. Container exits immediately / agent produces no reply
- 3. Mount Issues
- 4. Heartbeat / stale-session detection
- Container CLI (ncl) inside a session
- Restarting a session's container
- Manual Container Probes
- Provider SDK Options
- Rebuilding After Changes
- Clearing a Session
For development For launchd service (macOS), add to plist EnvironmentVariables: For systemd service (Linux), add to unit [Service] section: List sessions and their agent group / messaging group from the central DB pnpm exec tsx scripts/q.ts data/v2.db "SELECT id, agent_group_id, messaging_group_id, status, container_status, last_active FROM sessions" Or via the admin CLI ncl sessions list Did the message reach the container? (inbound.db, host writes / container reads) pnpm exec tsx scripts/q.ts data/v2-sessions/<group>/<session>/inbound.db \ Did the agent produce a reply? (outbound.db, container writes / host reads)
What does the debug skill do?
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.
How do I install it?
Run `npx skills add nanocoai/nanoclaw --skill debug --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From nanocoai/nanoclaw, a repository with 30,426 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.