debug

name	debug
description	Debug nano-core agent runtime issues (Docker default, host opt-in). Use when agent execution fails, runtime checks fail, or onboarding/startup is blocked.

nano-core Runtime Debugging

This guide covers host-side diagnosis for current runtime modes:

• Docker (default)
• Host runtime (advanced, explicit opt-in)

Runtime Architecture

Host process (src/index.ts)
  -> runtime selection (src/container-runtime.ts)
  -> agent execution (src/container-runner.ts)
     - Docker mode: docker run nano-core-agent:latest
     - Host mode: node container/agent-runner/dist/index.js

Key Log Locations

Log	Location	Purpose
App log	logs/nano-core.log	Router, scheduler, runtime orchestration
App error log	logs/nano-core.error.log	Host process failures
Runtime run log	groups/<folder>/logs/runtime-*.log	Per-run stdout/stderr, mounts, env diagnostics

Quick Health Checks

1) App build/runtime sanity

npm run typecheck
npm run build

2) Runtime mode resolution

node -e "import('./dist/container-runtime.js').then(m=>console.log(m.getContainerRuntime()))"

3) Docker availability (default)

docker --version
docker info >/dev/null && echo "Docker OK" || echo "Docker NOT running"

4) Host mode gating (advanced)

grep -E '^(CONTAINER_RUNTIME|NANO_CORE_ALLOW_HOST_RUNTIME|NANO_CORE_ALLOW_HOST_RUNTIME_IN_PROD)=' .env || true

Host mode requires:

• CONTAINER_RUNTIME=host
• NANO_CORE_ALLOW_HOST_RUNTIME=1

Production host mode additionally requires:

• NANO_CORE_ALLOW_HOST_RUNTIME_IN_PROD=1

Common Failure Modes

"Invalid CONTAINER_RUNTIME"

Cause: .env contains an unsupported value.

Fix:

sed -i.bak 's/^CONTAINER_RUNTIME=.*/CONTAINER_RUNTIME=auto/' .env

"No supported runtime found"

Cause: Docker unavailable and host mode not explicitly allowed.

Fix options:

1. Start Docker Desktop / Docker daemon.
2. Or explicitly enable host mode in .env:

CONTAINER_RUNTIME=host
NANO_CORE_ALLOW_HOST_RUNTIME=1

Runtime exits with code 1

Check newest runtime log:

ls -t groups/*/logs/runtime-*.log | head -1 | xargs -I{} sh -lc 'echo "== {} =="; tail -120 "{}"'

Then validate credentials:

grep -E '^(CLAUDE_CODE_OAUTH_TOKEN|ANTHROPIC_API_KEY|PI_API|PI_MODEL|ZAI_API_KEY)=' .env

Session resumption problems

Verify per-group session mount path exists:

ls -la data/pi/main/.pi 2>/dev/null || true

Ensure runtime logs show expected mounted session directory and no permission errors.

Manual Runtime Smoke Tests

Docker mode smoke

echo '{}' | docker run -i --entrypoint /bin/echo nano-core-agent:latest "Container OK"

Host mode smoke

npm --prefix container/agent-runner run build
CONTAINER_RUNTIME=host NANO_CORE_ALLOW_HOST_RUNTIME=1 NANO_CORE_DRY_RUN=1 npm run dev

Service-level Checks (launchd)

launchctl list | grep nano-core || true
launchctl kickstart -k gui/$(id -u)/com.nano-core
sleep 2
tail -80 logs/nano-core.log

One-Pass Diagnostics Script

echo "1) Node/build"
node --version
npm run -s build >/dev/null && echo "build OK" || echo "build FAIL"

echo "\n2) Docker"
docker info >/dev/null 2>&1 && echo "docker OK" || echo "docker NOT ready"

echo "\n3) Runtime policy"
grep -E '^(CONTAINER_RUNTIME|NANO_CORE_ALLOW_HOST_RUNTIME|NANO_CORE_ALLOW_HOST_RUNTIME_IN_PROD)=' .env || echo "no runtime env overrides"

echo "\n4) Latest runtime logs"
ls -t groups/*/logs/runtime-*.log 2>/dev/null | head -3 || echo "no runtime logs yet"

Escalation Data to Capture

If issue persists, capture and share:

1. logs/nano-core.log tail (last 120 lines)
2. Latest groups/<folder>/logs/runtime-*.log
3. Output of docker info (or host mode env flags)
4. Current .env runtime keys (redact secrets)