Drive and observe MARS through the embedded dashboard API.

Start The Dashboard

mars start runs a scoped single-repo lifecycle. mars serve runs the persistent orchestrator. Both can expose the embedded dashboard. The listener is always loopback-only. Page/login shells, embedded assets, and a minimal redacted status projection remain an observer surface. Repos, roles, telemetry, evolution, quality, throughput, orchestration, decisions, SSE, and browser mutations require MARS_DASHBOARD_CONTROL_SECRET with at least 32 bytes, login, the exact Host/Origin, and the current session CSRF token.

MARS_DASHBOARD_CONTROL_SECRET='<owner-provided-32+-byte-secret>' \
mars start --repo /path/to/repo \
  --dashboard-addr 127.0.0.1:9090 \
  --addr 127.0.0.1:9091 \
  --execution-profile host --acknowledge-host-execution

mars serve \
  --addr 127.0.0.1:9091 \
  --concurrency 2 \
  --execution-profile host --acknowledge-host-execution

open http://127.0.0.1:9090
curl http://127.0.0.1:9091/healthz
curl http://127.0.0.1:9090/api/status

Addresses

MARS uses two loopback-only HTTP surfaces during runtime. Keep them distinct when scripting checks or debugging a port issue.

curl http://127.0.0.1:9091/healthz
curl http://127.0.0.1:9090/api/status

Pages

The HTML pages are operator views. They do not replace repo-owned artifacts such as tickets, feature contracts, traces, release notes, or quality score documents.

Events Stream

GET /api/events is a server-sent-events stream. It requires an authenticated session even on loopback and accepts GET only. It sends an initial keepalive comment, replays buffered recent events, then streams new events as they are broadcast. Replay, event size, client count, and per-session connections are bounded. Event payloads are JSON strings with type and data fields.

curl -N http://127.0.0.1:9090/api/events

data: {"type":"status_change","data":"{\"state\":\"paused\"}"}

Control Endpoints

POST /api/login accepts only JSON containing the environment-configured secret and returns an opaque HttpOnly SameSite=Strict session cookie plus the session CSRF token. After the login-shell redirect, authenticated same-origin GET /api/session bootstraps the current CSRF without a second secret entry or URL/browser-storage persistence. Mutating endpoints require POST, that cookie, exact same-origin Origin, and X-MARS-CSRF-Token. Bodyless mutations reject any body; JSON controls reject unknown fields, trailing values, oversize values, and non-JSON content. They return JSON with {"ok":true} on success, or an error field when the request cannot be applied.

Status And Selection Endpoints

Read APIs

When the dashboard is created by the orchestrator, serve attaches authenticated read APIs that power the dashboard pages. Unauthenticated loopback requests receive 503 when no control secret exists or 401 when login is required. Treat these as local operational evidence views, not as durable storage.

Responses And Errors

Scripts should branch on HTTP status and then read the response body. The dashboard favors actionable text over opaque codes.

{"ok":true}

{"ok":false,"error":"repo_id and role are required"}

{"ok":false,"error":"emergency stop did not complete; inspect the owner-only local command log"}

Recipes

curl http://127.0.0.1:9090/api/repos
curl "http://127.0.0.1:9090/api/repo-roles?repo_id=REPO_ID"

curl http://127.0.0.1:9090/api/orchestration
curl "http://127.0.0.1:9090/api/orchestration/decisions?repo_id=REPO_ID"

Security

The dashboard API is an operator control surface. MARS binds it only to loopback. Optional remote browsing requires an exact HTTPS reverse-proxy origin selected by --dashboard-trusted-origin or MARS_DASHBOARD_TRUSTED_ORIGIN, and every remote route requires a valid session. Forwarded headers are ignored.

• Use 127.0.0.1:PORT for local-only operation.
• Set the control secret only through MARS_DASHBOARD_CONTROL_SECRET; never put it in flags, YAML, URLs, logs, or generated files.
• The embedded browser sends the secret only to the bounded login body; every later mutation uses the opaque session and session CSRF.
• Strict self-only CSP, safe DOM text construction, vendored pinned assets, and no runtime CDN make the dashboard usable with outbound networking disabled.
• Prefer repo-owned evidence and logs for audit trails; dashboard responses are live operational views.

Troubleshooting