Run doctor

GET/api/doctor

Checks the machine for problems across system, Docker, exposure, backups, watch, notifications, Proxmox and configuration, and returns one finding per check. Every warn and fail finding carries the command that fixes or investigates it.

Authorizations

Authorizationstringheader

The token you start the server with: homebutler serve --token <token>, or web.token in the config file. Send it as Authorization: Bearer <token>. When the server has a token, every /api/ route except the CORS preflight requires it, reads included.

Query parameters

serverstring

The name of a remote server from List servers. homebutler runs the command on it over SSH and returns its answer. Leave it out, name the local server, or name a server that is not in the config, to read this machine.

Example: nas

Response

200 · application/json

The findings and a count per severity. The example is shortened.

schema_versionintegerrequired

The version of this document's shape. It is 1.

timestampstringrequired

When the checks ran, RFC 3339 in UTC.

server_namestringrequired

The name of the server checked.

statusstringrequired

The worst severity among the findings.

Available options: passwarnfail

summaryobjectrequired

The number of findings at each severity.

findingsobject[]required

One entry per check.

cURLcURLPythonJavaScript

curl --request GET \
  --url 'http://localhost:8080/api/doctor?server=nas' \
  --header 'Authorization: Bearer <token>'

{
  "schema_version": 1,
  "timestamp": "2026-10-25T18:57:55Z",
  "server_name": "homelab",
  "status": "fail",
  "summary": {
    "pass": 0,
    "warn": 5,
    "fail": 2
  },
  "findings": [
    {
      "severity": "warn",
      "category": "exposure",
      "title": "6 port(s) are listening on all interfaces",
      "detail": "18601/tcp, 18610/tcp, 18611/tcp, 22/tcp, 3399/tcp, 8080/tcp",
      "action": "Make sure each one is intentional and protected by firewall, reverse proxy, or login where needed.",
      "command": "homebutler inventory scan",
      "runner": "mcp",
      "tool": "inventory_scan"
    },
    {
      "severity": "warn",
      "category": "backup",
      "title": "No backups found",
      "detail": "No .tar.gz backups found in /home/you/backups.",
      "action": "Create your first backup, then verify at least one important app with a drill.",
      "command": "homebutler backup",
      "runner": "mcp",
      "tool": "backup_create"
    },
    {
      "severity": "warn",
      "category": "proxmox",
      "title": "Proxmox endpoint \"pve\" accepts any certificate",
      "detail": "insecure: true disables certificate verification entirely, so anything on the network path can read the API token and answer for the endpoint.",
      "action": "Pin the certificate with fingerprint, or trust its issuer with ca_file, and remove insecure.",
      "command": "homebutler proxmox status --endpoint pve",
      "runner": "mcp",
      "tool": "proxmox_status"
    },
    {
      "severity": "warn",
      "category": "report",
      "title": "No report baseline yet",
      "detail": "Doctor did not find previous report snapshots.",
      "action": "Run report once so homebutler can notice what changes later.",
      "command": "homebutler report",
      "runner": "mcp",
      "tool": "report"
    },
    {
      "severity": "fail",
      "category": "proxmox",
      "title": "Proxmox endpoint \"pve\" has no readable collectors",
      "detail": "version: proxmox request /api2/json/version: Get \"https://127.0.0.1:8699/api2/json/version\": dial tcp 127.0.0.1:8699: connect: connection refused",
      "action": "Check network reachability to the configured host and port, and any firewall rules in between.",
      "command": "homebutler proxmox status --endpoint \"pve\"",
      "runner": "mcp",
      "tool": "proxmox_status"
    }
  ]
}