Repository navigation
ADR 0045
Status: accepted · Built: done · Date: 2026-11-22
Phase 2 of the ecosystem's ADR 0005. Built: the OpenAPI description (GET /openapi.json, every route with a summary and a tag, checked at start), GET /instance, the read-only metrics routes, the agent writing the uptime probes; the dashboard without volumes or VictoriaMetrics; the
metricsnetwork; the API door (/v1/* on the dashboard's domain, API_TOKEN). The update route the Studio calls comes with the provisioning bundle (phase 3), which defines how an instance updates.
The ecosystem's ADR 0005 has Kodentuzo Studio manage each team's Spotcraft instance, and it may do that only through the instance's API. The agent already answered the dashboard, but the dashboard had two other ways in: it queried VictoriaMetrics directly, and it wrote the uptime-probe targets to a shared volume. The API had no description a client outside this repository could use.
- The agent's API is the one way into an instance. The dashboard, the Studio and any other client use it. No client reads the server's files, its metrics or its Docker directly.
-
It describes itself in OpenAPI 3 at
GET /openapi.json, behind the same token as every route but/health. Every route has a summary and a tag (ROUTESinagent/src/app.ts); the agent refuses to start with a route that has none. -
GET /instancesays what the instance is: its version, its settings, how many apps it runs. -
Metrics are read through the API:
GET /metrics/queryandGET /metrics/query_rangepass a PromQL query to VictoriaMetrics' two query endpoints, and nothing else. VictoriaMetrics sits on its ownmetricsnetwork, with only vmagent (which writes) and the agent (which reads). - The agent writes the uptime-probe targets, at start and every minute. The dashboard has no volumes.
- The dashboard is a client of the API like any other. What it can do, the Studio can do through the same routes.
- A metrics query is one more hop: the dashboard asks the agent, which asks VictoriaMetrics. The queries are the same, with the same five-second budget.
- A change to an app reaches the uptime probes within a minute, not at once.
-
Clients other than the dashboard use the API door:
/v1/*on the dashboard's domain, withAPI_TOKEN. The dashboard forwards their requests to the agent, which still answers only the dashboard's address. - The update route the Studio calls comes with the provisioning bundle (phase 3), because the bundle defines how an instance updates itself.
Published from docs/. Edit the files there; changes here are overwritten.