Public Runtime Watchdog

This runbook keeps the public Vignette runtime recoverable after Windows reboot, update, or process crash. It covers:

engine gateway: http://127.0.0.1:9099
prod API: http://127.0.0.1:8001
Cloudflare tunnel for https://api-vignette.chanpaca.net

Secret Handling

Do not put secrets in scheduled task arguments.

The scripts use the existing runtime locations:

API secrets stay in apps/api/.env.
Cloudflared credentials stay under the current user's .cloudflared config.
Claude CLI OAuth/config stays in the current Windows user profile.

The installer creates a per-user interactive scheduled task. It starts at user logon and repeats as a watchdog. Fully unattended boot before any user logs in requires an operator-managed service account or Task Scheduler credential; do that in Windows, not by adding secrets to these scripts.

Install Or Update

From the repo root:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-public-runtime-task.ps1 -RunNow

The installer is idempotent. Re-running it updates the same task:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-public-runtime-task.ps1 -IntervalMinutes 5

Do not add future domains to the default watchdog until DNS and Cloudflare routing are live. For example, api-vnet.18ka.net is intentionally excluded from the default checks while that domain has no DNS. After a public domain is actually reachable, add it explicitly:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-public-runtime-task.ps1 `
  -AdditionalPublicHealthUrls https://api-vnet.18ka.net/health

Task name:

VignettePublicRuntimeWatchdog

Manual Start

Use this when you want to force a runtime restore immediately:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-public-runtime.ps1

start-public-runtime.ps1 now verifies or starts the engine gateway before it starts the prod API and cloudflared.

Health Checks

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\watch-public-runtime.ps1 -CheckOnly
Invoke-RestMethod http://127.0.0.1:9099/health
Invoke-RestMethod http://127.0.0.1:8001/health
Invoke-RestMethod https://api-vignette.chanpaca.net/health

Optional extra public host check, only after the host resolves:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\watch-public-runtime.ps1 `
  -CheckOnly `
  -AdditionalPublicHealthUrls https://api-vnet.18ka.net/health

Optional real Claude CLI readiness smoke:

Invoke-RestMethod http://127.0.0.1:9099/ready

/ready can consume a small Claude budget because it performs a real generation.

Logs And Task State

Get-ScheduledTask -TaskName VignettePublicRuntimeWatchdog
Get-ScheduledTaskInfo -TaskName VignettePublicRuntimeWatchdog
Get-Content .\public-runtime-watchdog.log -Tail 50
Get-Content .\apps\api\engine.public.err.log -Tail 50
Get-Content .\apps\api\api.public.err.log -Tail 50
Get-Content .\cloudflared.public.err.log -Tail 50

Remove

Unregister-ScheduledTask -TaskName VignettePublicRuntimeWatchdog -Confirm:$false

Recovery Notes

If local health is good but public health fails, inspect the cloudflared process and C:\Users\<user>\.cloudflared\vignette-config.yml.

If engine health fails, verify that claude runs for the same Windows user that owns the scheduled task and that the user has completed Claude CLI login.

If API health fails with environment, db, or auth configuration errors, inspect apps/api/.env; do not copy secret values into scripts or task arguments.

3.6 KiB Raw Blame History