---
canonical: "https://agi-labo.com/tools/cockpit/docs/cockpit-cli/reference/doctor"
title: "cockpit doctor"
description: "cockpit doctorの構文、オプション、結果、制約をcockpit CLIの正本から自動生成したリファレンスです。"
section: "リファレンス"
order: 122
pageType: reference
lastVerifiedVersion: 4.61.0
lastVerifiedAt: "2026-08-27"
draft: false
surfaces:
  - cli
operatingSystems:
  - windows
  - macos
  - linux
plans:
  - guest
  - member
navigation: false
---

このReference本文は、アプリが配布するcockpit CLIヘルプと同じ英語の正本から自動生成されています。日本語の概念説明と安全な使い方は[cockpit CLI](/tools/cockpit/docs/cockpit-cli)を参照してください。

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.