Vigolium API Reference, Diagnostics - Vigolium Documentation

GET /api/diagnostics, System Readiness Check

Returns a diagnostic report checking database connectivity, agent provider readiness, third-party tools, and directory configuration. Useful for verifying the scanner is ready to operate before starting scans. Auth: Viewer (requires Bearer token)

curl -s -H "Authorization: Bearer $TOKEN" http://localhost:9002/api/diagnostics | jq .

{
  "status": "degraded",
  "timestamp": "2026-04-29T03:40:08+08:00",
  "database": {
    "status": "ok",
    "message": "driver=sqlite"
  },
  "queue": {
    "status": "ok",
    "message": "depth=0"
  },
  "agent": {
    "status": "ok",
    "name": "olium",
    "provider": "openai-codex-oauth",
    "model": "gpt-5.5"
  },
  "browser": {
    "status": "warning",
    "message": "disabled in config"
  },
  "tools": {
    "chromium": {
      "status": "ok",
      "path": "/opt/homebrew/bin/chromium"
    }
  },
  "templates_dir": {
    "status": "ok",
    "message": "path=~/.vigolium/prompts, templates=38"
  },
  "sessions_dir": {
    "status": "ok",
    "message": "path=~/.vigolium/agent-sessions, writable=true"
  }
}

Top-Level Status

Value	Meaning
`ready`	All checks passed
`degraded`	Some non-critical checks failed (e.g., optional tool missing, browser disabled)
`not_ready`	Critical checks failed (database or agent unavailable)

Check Statuses

Each individual check returns one of: ok, warning, error.

Checks Performed

Check	Critical	Description
`database`	Yes	Pings the database with a 2s timeout
`agent`	Yes	Resolves the configured olium provider and confirms credentials are available
`queue`	No	Reports queue depth and error counts
`browser`	No	Checks `agent-browser` binary if enabled in config
`tools.chromium`	No	Resolves the chromium/chrome binary (fallbacks: `chromium-browser`, `google-chrome`, `google-chrome-stable`). On the one-shot CLI paths it also smoke-launches the browser — see the note below
`tools.piolium`	No	Reports whether the optional piolium harness is installed under `~/.piolium`
`templates_dir`	No	Verifies prompt templates directory exists and contains `.md` files
`sessions_dir`	No	Verifies agent sessions directory exists and is writable

Browser smoke-test on the CLI paths. On the one-shot CLI paths — vigolium doctor and the first-run dependency check — the tools.chromium check goes beyond reading the --version banner: it actually launches the resolved Chromium headless, performing the same DevTools remote-debugging handshake the spider relies on, in an isolated self-cleaning user-data dir, bounded to ~30s. A binary that prints a version but SIGTRAPs / crashes on real launch (seen with some distro Chromium builds) or is missing a runtime shared library is downgraded from ok to warning, carrying a remedy: run vigolium doctor --fix --only chrome to download a working Chrome for Testing, or point spidering.browser_path at a working browser. The server GET /api/diagnostics endpoint leaves this heavy probe off to stay a cheap, poll-safe readout.

CLI Equivalent

The same checks are available via the CLI without a running server:

# Colored console output
vigolium doctor

# JSON output
vigolium doctor --json

The CLI version omits the queue check since the queue is only available when the server is running.

​GET /api/diagnostics, System Readiness Check

​Top-Level Status

​Check Statuses

​Checks Performed

​CLI Equivalent

GET /api/diagnostics, System Readiness Check

Top-Level Status

Check Statuses

Checks Performed

CLI Equivalent