Local API and dashboard¶
harness api serve --path <project> starts a FastAPI application (requires the api extra) over
the same application layer as the CLI. It serves one project.
Warning
Since 2.0 (#18) the api section of project.yaml, which harness init writes, requires a
bearer token on every route and gives each person a role. A project without that section has
no authentication, no roles and no multi-user model: anyone who reaches the port can read every
run. After 2.0.1 (CHANGELOG, Unreleased) such an API records no decision (the POST answers 403 and names
harness gate decide); before, it recorded one under any actor id outside the agent, validator
and harness namespaces. Either way, keep the server on the loopback default (--host 127.0.0.1):
the token travels over plain HTTP and the harness is not a sandbox for the host it runs on. See
SECURITY.md.
harness api serve --path . --host 127.0.0.1 --port 8765
Authentication and roles¶
With the api section (and api.auth not off), every request, the dashboard page and
/openapi.json included, must carry Authorization: Bearer TOKEN; without a valid token the
answer is 401 with WWW-Authenticate: Bearer. The token is accepted in that header only
(never in a query string, which servers log) and compared in constant time. The access log of
harness api serve (standard output) records the client, method, path, HTTP version and status of
each request, never its query string, so a token sent there by mistake is refused and not written.
| Role | May |
|---|---|
viewer |
Every GET: the dashboard, runs, briefs, traces, evidence, findings, inbox, registry |
reviewer |
What a viewer may, and record decisions (POST /api/runs/{run}/decision) |
admin |
What a reviewer may, and read the effective configuration (GET /api/config) |
A request whose role is not enough is answered 403. Tokens never appear in project.yaml:
api:
auth: token # token (the default when the section is present) or off
tokenEnv: HARNESS_API_TOKEN # the variable holding the token of the person who starts the server
tokenUser: human.web # the actor id recorded on that person's decisions
tokenRole: admin # that person's role
users: # further people: id, role and the NAME of their token's variable
- id: alice
role: reviewer
tokenEnv: HARNESS_API_TOKEN_ALICE
| Key | Default | Meaning |
|---|---|---|
auth |
token with the section, no authentication without it |
off serves without authentication, as in 1.0.0 |
tokenEnv |
HARNESS_API_TOKEN |
Variable holding the start token; when it is not set, harness api serve generates one |
tokenUser |
human.web |
Actor id of the start token (a person: not agent.*, validator.* or harness.*) |
tokenRole |
admin |
Role of the start token |
users |
none | People with an id (an actor id), a role and a tokenEnv |
How the token is shown. When tokenEnv is set, harness api serve uses its value and prints
only the variable's name. When it is not set, the server generates a random token (Python
secrets, 32 bytes) and prints it once, on standard error, at start; it is not written to any
file, event, artifact, audit record or log. Set tokenEnv to choose the token yourself, for
example when standard error is captured by a log. A user whose variable is not set cannot sign in
(a warning names the user); a token shorter than 16 characters, two people sharing one token, a
user id in the agent, validator or harness namespace, an invalid api section and a
project.yaml that cannot be read stop the server before it listens (fail closed). The values of every token variable are redacted from stored artifacts.
Decisions. The authenticated person is the decider: the request's actor_id must be absent
(or empty) or equal to their user id, otherwise 403. Each decision request appends an
attempted record, before anything is decided, and then a refused or recorded record to
.harness/audit/api-decisions.jsonl (mode 0600, append-only): time, user id, role, route, run,
decision, ChangeSet digest, requested actor id, client host, outcome, HTTP status and the reason or
the decision id. If the attempt cannot be written, nothing is decided (500). The log never
holds a token. Without authentication (no api section, or api.auth: off) the route answers
403 and records nothing: decide with harness gate decide, or turn authentication on.
Dashboard. Without a token GET / answers 401 with a sign-in page that asks for the token,
keeps it in the tab's sessionStorage and loads the dashboard with it. Every call of the dashboard
goes through one request() helper that sends the token as Authorization: Bearer and signs out
when the server refuses it. Closing the tab forgets the token.
harness config validate shows the effective settings under api (variable names and whether
each is set, never a value).
Routes¶
| Method | Path | Returns | Errors |
|---|---|---|---|
GET |
/api/health |
The doctor result for the project (status, checks) |
— |
GET |
/api/session |
Who the request is authenticated as (userId, role), or {"authentication": "off"} (#18) |
401 |
GET |
/api/config |
The harness config validate result; role admin (#18) |
400, 401, 403 |
GET |
/api/runs |
Runs of the project, newest first | 400 |
GET |
/api/runs/{run} |
Status projection: execution, phases, validation summary, findings summary, gate, human decision, event count, event-chain check, metrics | 404 |
GET |
/api/runs/{run}/review?diff=false |
The decision brief (what was asked, what changed, risks, what was verified on which digest and what was not, exceptions, history, delta since the last decision, next commands); diff=true adds the redacted diff |
404 |
GET |
/api/inbox |
What waits for a person, oldest first: a decision, clarification answers and, since #55, a deferred verification waiting for evidence or a preflight waiting for a decision and, since #73, every other wait before DECISION (plan, decomposition, acceptance, architecture, contract, with the digest and the answering command) |
400 |
GET |
/api/runs/{run}/verification |
The verification plan, preflight, certification, deferred items and checklist of a run (#55) | 404 |
GET |
/api/registry |
The projects of the run registry outside the workspaces (runtime.stateDir) with their latest runs (#55) |
400 |
GET |
/api/exceptions?status=all\|active\|expired |
The exception ledger (review.exceptions) |
400 |
GET |
/api/runs/{run}/trace?format=json\|markdown\|jsonl\|sarif |
The trace in the requested format (application/json, text/markdown, application/x-ndjson, application/sarif+json); default json |
404, 409 (run does not verify under governance.verifyRecords) |
GET |
/api/runs/{run}/evidence |
Evidence records with artifact references | 404 |
GET |
/api/runs/{run}/findings |
Structured findings | 404 |
GET |
/api/runs/{run}/retrospective |
Non-mutating retrospective | 404 |
GET |
/api/metrics?since=&task=&model=&agent=&all_repos=false |
The report of harness metrics --format json (#58): computed from the records, no model call |
400 |
GET |
/api/metrics/report (same parameters) |
The self-contained HTML report of harness metrics --format html (#58) |
400 |
POST |
/api/runs/{run}/decision |
The recorded decision and the updated execution | 403, 409, 422 |
GET |
/ |
The embedded dashboard (HTML) | — |
The thesis cut had nine routes: seven queries, one decision POST and the dashboard; the inbox,
exceptions and review routes were added in 2.0 (#53), the session and configuration routes with
authentication (#18). Under authentication every route also answers 401 without a valid token,
and the decision route 403 without the role reviewer; without authentication the decision
route always answers 403. {run} also accepts latest and a unique
prefix of a run id. The OpenAPI document is available at /openapi.json and the interactive docs at
/docs (FastAPI defaults).
Recording a decision¶
The request body uses snake_case keys and rejects unknown keys (a camelCase body returns 422):
curl -s -X POST http://127.0.0.1:8765/api/runs/<run>/decision \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $HARNESS_API_TOKEN" \
-d '{"decision": "APPROVE",
"change_set_digest": "sha256:<current digest from GET /api/runs/<run>>",
"rationale": "Acceptance criteria and evidence reviewed",
"continue_after": true}'
| Field | Type | Default |
|---|---|---|
decision |
APPROVE, APPROVE_EXCEPTION, REQUEST_CHANGES, REJECT |
required |
change_set_digest |
string | required |
rationale |
string | required |
actor_id |
string | under authentication, the authenticated user (any other value is refused with 403); without it, the Git user under governance.deciderIdentity: git (human.web with a warnings entry in the response when Git has no identity), otherwise human.web |
continue_after |
boolean | true |
expires_in, expires_at, scope, alternative_evidence, follow_up |
exception options of APPROVE_EXCEPTION under review.exceptions (see configuration) |
none |
checked_items |
checklist items the person verified (review.manualChecklist, see configuration) |
none |
Every policy violation of harness gate decide (stale digest, APPROVE over a gate that did not
pass, run not in DECISION, exception without rationale) is returned as 409 with the reason in
detail, for example {"detail": "human decisions are accepted only in DECISION"}. An
actor_id in the namespace of an agent (agent.*), a validator (validator.*) or the harness
(harness.*) is refused with 403 whatever the configuration.
With governance.trustedHosts (written by harness init: 127.0.0.1, localhost, ::1) every
route answers 400 to a request whose Host header is not one of those names, so a web page
cannot reach the server through DNS rebinding. Without the key every host is accepted, as in 1.0.0.
The host check runs before the authentication.
Dashboard¶
The page served at / (behind the sign-in page under authentication) shows who is signed in,
lists the runs, shows the decision brief of the selected run (the full
status projection is under a collapsed section) and lets a person record APPROVE,
REQUEST_CHANGES, APPROVE_EXCEPTION or REJECT against the current ChangeSet digest, with an
actor and a rationale; a confirmation shows the decision, the digest and the files before it is
sent. Its left column lists what waits for a person (/api/inbox) and the page refreshes every
5 seconds without discarding a rationale being typed. Since #55 the brief shows the certification
and the deferred items, the decision form lists the checklist items to tick, and a section lists
the repositories of the run registry (/api/registry). It contains no policy or workflow logic: it calls the routes
above. Since #58 a Metrics tab shows the totals of /api/metrics and the self-contained report of
/api/metrics/report, fetched with the same token and shown in a frame from its text (optionally
for every repository of the registry). The static prototype that lived in web/ targeted routes that never existed and was
removed in v0.8.1 (issue #12).