Skip to content

development-console.md

Latest commit

 

History

History
139 lines (91 loc) · 8.32 KB

development-console.md

File metadata and controls

139 lines (91 loc) · 8.32 KB
Raw

Development Console

The Development Console is an Ingress-protected, observer-only verification surface. It uses the same HomeAssistantReadPort and Supervisor adapter as the MCP observer. It does not proxy arbitrary Home Assistant routes and it cannot execute mutations.

For per-client capability verification, including the distinction between granted, implemented, reachable and executable permissions, see Capability verification.

Endpoints

  • GET /api/development/catalog — bounded operation and pack catalog.
  • POST /api/development/run — enqueue one operation, a pack (pack:<name>), or all; returns 202 and a bounded job_id immediately.
  • GET /api/development/jobs/{job_id} — read queued/running/completed status and incremental results for a development job.
  • GET /api/development/reports — sanitized persisted reports.
  • GET /api/health/details — independent upstream checks.
  • GET /api/ui/context — locale/theme compatibility context.
  • POST /api/operator/preview — validation/diff preview only; execution remains disabled.
  • GET /api/operator/status — effective operator state and registered mutation tools; currently reports an empty mutation catalog.

Asynchronous job contract

POST /api/development/run returns 202 Accepted and a Location header pointing to the job resource:

HTTP/1.1 202 Accepted
Location: /api/development/jobs/7f...
{"status":"queued","job_id":"7f...","operation":"all"}

Poll the Location every 250–1000 ms with backoff. Valid states are queued, running, completed, warning and error. results is monotonic: completed operation results remain available in later snapshots. warning means the job finished but one or more probes returned an empty or degraded result; error means at least one probe or report persistence failed.

The Ingress bootstrap keeps each check independent and reports incremental progress for readiness, clients, audit, catalog, development reports, UI context, health details, operator status, and operator service policy. A failed bootstrap shows the affected path, sanitized HTTP/error code, duration, and the checks that completed successfully; it does not collapse all failures into an opaque global message. Retry starts a fresh versioned bootstrap and ignores stale progress from the previous attempt.

The MCP discovery contract advertises the same observer surface: gateway_diagnostics, inventory, states, automations, configuration, services, events, history, logbook, devices, areas, floors, labels, entity registry, scripts, scenes, helpers and integrations. The MCP functions call the same application read port rather than duplicating upstream HTTP logic.

Diagnostic transport failures are classified without exposing upstream exception text:

  • home_assistant_transport_timeout — bounded request timeout;
  • home_assistant_transport_connection — connection establishment failure;
  • home_assistant_transport_network — other network-layer failure;
  • home_assistant_transport_unavailable — remaining HTTPX transport failure.

Transport failures include only the logical endpoint and bounded parameter names. History and Logbook timestamp path values and entity values are never included in diagnostics. Only transient transport failures are retried once; upstream HTTP validation failures are not retried.

A successful request that returns an empty collection is not treated as a transport failure. Development probes expose it as status="warning", reason="empty_result", and count=0, so a missing registry or unexpectedly empty dataset is visible for investigation.

All management endpoints require the Supervisor Ingress identity. /health and /ready remain safe health endpoints.

Local port and MCP transport diagnostics

The catalog includes gateway_ports. It performs only bounded checks from inside the Gateway container:

  • verifies that the configured internal listener accepts a local TCP connection;
  • checks GET /health locally and expects 200;
  • checks /mcp/ locally without credentials and expects the authentication boundary (401);
  • reports the configured bind host and internal port;
  • marks Supervisor host-port publication and LAN firewall reachability as not_verifiable_from_app_container.

This operation never invokes a shell, scans arbitrary ports, runs nmap/ss, probes arbitrary LAN addresses, or reads credentials. A successful local check does not prove that a host port is published. Verify the external mapping from a separate machine using the port declared by the App metadata.

MCP Host allowlist configuration

mcp_allowed_hosts is a global transport setting, not a per-client permission list. It validates the HTTP Host value used to reach the Gateway before the Bearer token is resolved.

In the Supervisor App configuration, enter a comma-separated list of destination hosts, without ports:

localhost,127.0.0.1,[::1],homeassistant,homeassistant.local,192.168.20.101

Use the host or IP that appears in the MCP URL:

  • URL http://192.168.20.101:18099/mcp/ → allow 192.168.20.101;
  • URL http://ai01.lan:18099/mcp/ → allow ai01.lan.

This is not the source IP of the machine running Hermes or OpenClaw. Do not add the MCP port (:18099) and do not use *; the latter disables the DNS-rebinding protection. Client identity, Bearer tokens and capabilities are configured separately and remain per client.

Upstream health contract

GET /api/health/details returns a bounded object:

{
  "status": "ready|degraded|unavailable",
  "checks": [
    {
      "name": "core|states|services|events|recorder|logbook",
      "status": "ok|error",
      "latency_ms": 12,
      "http_status": 200,
      "code": null
    }
  ]
}

recorder probes /history/period with a bounded one-hour start window. logbook probes /logbook with the same type of window. Errors contain a safe code, never authorization headers, response bodies, cookies, tokens, or query values.

Run-all and diagnostics

Run-all preserves one result per catalog operation. A failed result includes the operation, status, count, duration and a sanitized reason. The UI provides:

  • individual execution;
  • retry for the failed operation;
  • copy of the sanitized operation/status/reason diagnostic;
  • JSON export containing health, current results and the latest reports.

The export is generated locally in the browser and is not uploaded by the gateway.

Historical evidence

Reports persist bounded results, counts, status and schema fingerprints. The stable comparison object contains the previous report ID, total count delta and schema change flag. comparison_details contains per-operation count/status changes and explicit status regressions/recoveries without changing the original comparison contract.

A regression means an operation changed from ok to a non-OK status. This is evidence of a change, not proof of root cause; correlate it with the upstream health checks and Home Assistant release state.

Locale and theme

The frontend supports English, Spanish, French, German, Portuguese, Italian, Chinese, Japanese, Russian, Hindi and Arabic. Locale resolution is:

  1. local browser override;
  2. Home Assistant compatibility context;
  3. language-base normalization (es-MX → es);
  4. English fallback for missing keys or unsupported languages.

Theme resolution supports light, dark and auto, with prefers-color-scheme fallback. Decorative animation stops under prefers-reduced-motion.

Operator preview boundary

Preview operations are allowlisted and capability-matched:

  • ha.call_service → ha.write.services;
  • ha.update_automation → ha.write.automations;
  • ha.update_config → ha.write.configuration (reserved; no configuration mutation tool is registered).

The preview rejects oversized state maps and fields whose names indicate tokens, passwords, secrets, cookies, authorization or API keys. Every response declares approval, idempotency and rollback as requirements. No service call, configuration write or automation write is performed.

The operator safety framework is documented in operator-profile.md. It remains disabled even if the feature flag is configured: no mutation adapter is registered until the Home Assistant contract, approval, idempotency, audit, rollback and live verification gates are closed.