Context

The Dockerfile uses netclawd directly as PID 1 (ENTRYPOINT ["/usr/local/bin/netclawd"]). This causes the container to exit whenever the daemon restarts — which happens during:

• netclaw init wizard's health check step (sends POST /api/lifecycle/shutdown?reason=config-update)
• Configuration changes that trigger a daemon restart
• Any graceful shutdown/restart cycle

This makes it impossible to run the init wizard via docker exec — the wizard kills the daemon at step 10, the container exits, and the interactive session is lost.

Solution

1. Wrapper entrypoint script

Replace the direct netclawd entrypoint with a bash wrapper that restarts the daemon when it exits:

#!/bin/bash
trap 'kill $PID; wait $PID; exit 0' SIGTERM SIGINT

while true; do
    netclawd &
    PID=$!
    wait $PID
    echo "Daemon exited ($?), restarting in 2s..."
    sleep 2
done

• SIGTERM/SIGINT are forwarded to the daemon so docker stop works cleanly
• The 2-second delay prevents tight restart loops on persistent failures
• The container stays alive across daemon restarts, preserving docker exec sessions

2. Docker HEALTHCHECK

Add a HEALTHCHECK instruction using the existing liveness endpoint:

HEALTHCHECK --interval=15s --timeout=5s --start-period=30s --retries=3 \
  CMD curl -sf http://127.0.0.1:5199/api/health/ready || exit 1

• --start-period=30s: Grace period for initial boot (skill sync, migrations, etc.)
• --retries=3 at --interval=15s: ~45 seconds of sustained failure before marking unhealthy — enough to ride out a normal config-triggered restart (5-10 seconds)
• Uses /api/health/ready (simple liveness). Will switch to /api/health/status once Health status endpoint should return 503 on sustained connector/provider failures #744 adds meaningful HTTP status codes.

Key Files

• docker/Dockerfile — entrypoint and HEALTHCHECK changes
• docker/entrypoint.sh — new wrapper script

Related

• Health status endpoint should return 503 on sustained connector/provider failures #744 — meaningful HTTP status codes on /api/health/status (future improvement)
• docs(openspec): draft Discord channel interactions planning spec #713 — Discord integration PR where this was discovered