THE FIELD GUIDE / OPERATIONS
Troubleshooting the workbench
Start with the failure stage and inspect the relevant evidence.
Controller startup fails
docker compose ps
docker compose logs --tail=100 app worker caddyCheck .env, port conflicts, persistent-volume access and control-network overlap. Keep DOMAIN and PUBLIC_URL aligned with the address you actually use.
A target connection fails
Verify controller-to-target SSH reachability, its port and pinned fingerprint. Inspect the managed account and bridge through a trusted console. For IAP, distinguish cloud IAM/tunnel failures from guest SSH authentication failures; verify CLI identity in both app and worker containers.
An AI run is failing
Open AI activity and its stage details. Check the saved-settings connection test, model choice, provider credentials, rate limits and worker backoff. Inspect the selected pacing/spend mode, provider Retry-After, retry eligibility and configuration blockers. A manual retry cannot bypass pause, provider delay or shared budget reservations.
Collector identity or delivery needs attention
Update the controller/workers and verify the collector installation when an old generic Process identity unverified warning persists. A valid zero Linux start tick is supported; changed or incomplete identities still need investigation. Check whether an eBPF warning belongs to the current run, then inspect queue bytes, backlog age, reasoned loss counters and last delivery. Historical loss remains reviewable after an active warning clears.
Patching is waiting
Inspect maintenance windows, schedule start windows, host freshness, existing jobs, recovery holds and policy changes. An expected installation estimate is distinct from a priority deadline. Reconcile interrupted work before retrying.
The certificate is untrusted
Trust the local Caddy CA on the client, or configure a certificate/ACME profile appropriate to the hostname. Public ACME validation needs the expected external ports even when Docker publishes alternate ports.
Open the application reference for capability scope and technical details.
Open Open OPERATIONS.md on GitHub ↗