cockpit doctor

This reference is generated from the same canonical source distributed as cockpit CLI help. See Cockpit CLI for concepts and safe operating guidance.

Usage: cockpit doctor [--heap-profile start|stop|status]

Cross-checks cli-runtime.json and AGI_COCKPIT_*_PORT overrides against the local process. The result includes instance, the local Cockpit this command resolved as its target (production, dev, or dev-task-<hash>), derived from the runtime file or inherited IPC directory actually used. pidVisibility is alive, dead, or unknown; a sandbox can make a running process unknown. pidAlive remains for compatibility and is true only for alive.

For each local service (taskPort, autorunPort, cockpitPort, askPort), the result keeps the existing runtime/environment/effective port and listening fields and adds directlyReachable, which describes what this CLI caller can reach over loopback rather than claiming the port is stopped. At the report level, transports.loopback and transports.fileIpc show each task API authentication attempt and its failure reason, directlyReachable summarizes direct task API reachability, and effectiveTransport is loopback, file, or null. The task check requires a successful request with the advertised token and a 401/403 response with an invalid token. A loopback failure is followed by the same check through file IPC.

Task and talk commands recover an injected stale connection only when its IPC directory proves that the replacement runtime belongs to the same Cockpit instance. Other explicit connections never redirect to the runtime file or its file bridge. A CLI bound to one local instance ignores inherited connection settings that point at another; if it would still send there, it fails with code: "instance_mismatch" before any request is sent. Local JSON results include the same instance field. Commands that target another machine with --host omit it.

crashDumps summarizes the local crash dumps of that Cockpit: how many came from Cockpit itself, how many came from unrelated child processes that inherited the crash handler, how many could not be identified, how many dumps are retained, and how many were deleted as external or over the retention limit. It is null until Cockpit has scanned its crash directory once.

fileWatchers summarizes the file watchers the main process holds: the total, the split between chokidar and fs watchers, per-purpose counters (task-status, file-watch, creative-studio-workspaces, …) with how many directories each purpose watches and how many entries those directories actually hold on disk, and the largest watched directories by entry count. Entry counts are read from the directory itself, so a watcher that fell back to a huge parent directory is visible even before it admits any child. At most 256 directories per watcher are measured; measuredDirectories reports how many of watchedDirectories were counted. Directory paths are hashed. It comes from the latest main-process-metrics.jsonl sample and is null until Cockpit has written one. A watcher whose directory holds tens of thousands of entries rescans that directory on every change and is the shape of a main-process memory leak.

This is the app-reachability diagnostic. It is not cockpit app doctor, which inspects Android/iOS App Surface targets.

--heap-profile start begins a V8 sampling heap profile of the main process, --heap-profile stop ends it and writes a .heapprofile file under heap-profiles/ in the Cockpit diagnostics directory, and --heap-profile status reports whether one is running. The JSON result includes directory and, after a stop, filePath. The main process also starts a sampling profile on its own when its JS heap passes 1.5 GB or grows by more than 300 MB in one minute, and stops it at about 2.75 GB or after 60 seconds. An automatic profile is taken once per episode: it does not start again until the heap has fallen back below 1 GB, so a process that stays large writes one profile rather than one per minute. Sampling is used rather than a full heap snapshot because taking a full snapshot near the heap limit can itself exhaust memory. Profiles record allocation stacks only; task IDs are hashed in metrics and no prompt, message, or tool output is written.

Exit 0 when either loopback or file IPC authenticates with the task API, including when PID visibility is unknown. Exit 7 only when neither transport authenticates, including when the runtime file is unavailable and no transport can be selected.