Skip to main content
Features Cart

Docs Concepts

Watchdog architecture

The Power Claude proxy is a single Node.js process that listens on localhost:3456. By design, it does very little: parse incoming requests, pick an eligible account, forward upstream, parse rate-limit headers off the response. Lots of things can crash a Node process, and the proxy crashing silently is the worst possible failure mode — your client sees connection refused and reports it as "Anthropic is down."

The watchdog exists so that doesn't happen.

The supervisor

A user-mode systemd unit, claude-watchdog.service, owns the proxy lifecycle:

[Unit]
Description=Power Claude proxy watchdog
After=network-online.target

[Service]
Type=simple
ExecStartPre=/bin/sh -c "rm -f $HOME/.power-claude/state/proxy.pid"
ExecStart=/home/USER/.power-claude/bin/proxy
Restart=always
RestartSec=2
KillMode=process

[Install]
WantedBy=default.target

Two non-obvious lines:

  • ExecStartPre clears the PID file. A hard kill (OOM, kill -9, machine reboot) leaves a stale PID file behind. Without clearing it, the proxy refuses to start because it thinks another instance is running.
  • KillMode=process (NON-NEGOTIABLE). The default control-group mode SIGTERMs the entire cgroup on every restart attempt — and because setsid doesn't escape the cgroup, even properly-detached child processes get killed too. process mode kills only the main PID, leaving short-lived helpers alone. This is the difference between a watchdog that supervises and one that periodically annihilates its supervisee.

What the watchdog does NOT do

  • It does not inspect proxy behavior. If the proxy is running but stuck in a deadlock, the watchdog won't notice. The proxy has its own liveness check (liveness.sh) that pings itself and triggers a self-restart if unresponsive — that's a separate concern from "is the process alive at all."
  • It does not manage credentials, rotation, or any business logic. The watchdog's only job is "keep the process running."
  • It is not a Docker container or a system service. It runs as the same user that owns your Claude credentials, so credential file ownership is consistent.

Inspecting the watchdog

systemctl --user status claude-watchdog.service
journalctl --user -u claude-watchdog.service -n 100

Healthy output: active (running) with the proxy PID visible. If the unit is failed, the log usually shows why on the last 5-10 lines.

Restart loops

If the watchdog and proxy are caught in a rapid restart loop (proxy crashes immediately, watchdog restarts immediately, repeat), systemd will eventually give up — the unit goes into failed state with a "start-limit-hit" message. Clear it with:

systemctl --user reset-failed claude-watchdog.service
systemctl --user start claude-watchdog.service

…and then read the journal to find out why the proxy was crashing in the first place. The watchdog won't keep that secret; it just stops trying once it's clearly hopeless.

Why user-mode, not system

A system-wide unit would need root, and a credential leak in proxy code would then have root reach. User-mode keeps the blast radius at "things this user can touch" — which is the right boundary for a tool that holds your API credentials.