> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Run the read-only health walk > Runs `narya doctor`'s own walk over this installation — home directory, config, host lock, socket, store, sessions, package jobs, tool servers, credentials, binary and terminal — and answers both the rendered text and the structured lines behind it. Read-only throughout: every check reads, the store is opened read-only, and a finding names the command that repairs it rather than running one. It exists so a client does not have to compile the walk to offer `/doctor`. The walk lives with the engine, and the things a caller knows about itself that a host cannot — which binary is asking, which build produced it, what the caller's own terminal can render, and which desktop helpers the caller can actually deliver through — travel as parameters rather than being guessed at from the host's process. A host that is not running cannot answer this at all, which is the one case a client handles itself: it says so and names `narya doctor`, the command that walks a machine whose host is down. One line stays the HOST's own fact whatever a caller says: the keychain check describes the session the host process runs in, since that is the process that stores and reads a credential. ## OpenAPI ````yaml /pt/openapi/v3-current/narya.yaml get /v1/doctor openapi: 3.1.0 info: title: Narya Host API version: 1.0.0 description: >- The contract between the Narya host and every client. One long-lived host serves this API over a Unix socket in your Narya home. The terminal client and the one-shot command that Lerian ships drive this API, and a client you write drives the same one. Requests authenticate with a bearer token issued by the identity provider the host is configured with. An operation that declares another security scheme also accepts that credential. A request without a valid credential gets 401 with NRY-0011. A caller whose role lacks the permission an operation needs gets 403 with NRY-0028. Submitting a message returns 202 with a turn id. Everything the turn produces streams over GET /v1/events as server-sent events with a typed envelope, and a stream resumes from a Last-Event-ID header. One error envelope: code, title and message. Codes are NRY- followed by four digits. Cursors are opaque. servers: [] security: - bearerAuth: [] tags: - name: host description: The host process itself — version, uptime, mode, store. - name: sessions description: Durable conversation containers. Archive, never destroy. - name: messages description: Submitting work into a session and interrupting it. - name: events description: The server-sent event stream every client consumes. - name: lanes description: Parallel tracks inside a session — main, subagent, side. - name: agents description: Named recipes — instructions, tools, model, policy. Read-only in v1. - name: ladder description: >- What a person can type: the skills and command files in force for one repository, and expanding one into text. Five origins merged, nearest winning a name, the repository's own rungs gated on trust. - name: permissions description: Pending permission asks, decisions, and the decision audit. - name: intercom description: Sessions on one machine finding and messaging each other. - name: packages description: The one thing a user installs — resources, Go code, or both. - name: extensions description: >- Host-side extensions and the operations each exposes over the wire. This is the generic lane a host extension uses to serve its own client half (a TUI component, a web panel) or any API-only consumer, without adding routes to this contract. - name: workflows description: Deterministic multi-agent orchestration runs. - name: providers description: Model suppliers, their auth state, and the model catalogue. - name: monitors description: >- Long-running watchers a session keeps beside its conversation — a test runner in watch mode, a build, a log being followed. Started by the model or by the person, always listed, always killable. - name: records description: The queryable local record of everything that happened. - name: environments description: >- Where a session's code lives and its commands run — this machine, or a container narya operates. A session that names none runs here. - name: schedules description: >- Work the host's own clock starts with nobody present — a repository, a prompt, a rule and what one fire may spend. Cancel, never destroy. - name: sharing description: >- Publishing a session from a developer's own home to the organisation's, and what is held back before a byte leaves the machine. - name: refinements description: >- What this owner has taught narya and allowed it to keep — distilled facts, and the skills, agents and commands the model wrote for itself. Propose, read, consent, roll back. Nothing here fires until a person answers. - name: platform description: >- Calls Lerian's control plane made to a home it hosts, as this home recorded them. paths: /v1/doctor: get: tags: - host summary: Run the read-only health walk description: >- Runs `narya doctor`'s own walk over this installation — home directory, config, host lock, socket, store, sessions, package jobs, tool servers, credentials, binary and terminal — and answers both the rendered text and the structured lines behind it. Read-only throughout: every check reads, the store is opened read-only, and a finding names the command that repairs it rather than running one. It exists so a client does not have to compile the walk to offer `/doctor`. The walk lives with the engine, and the things a caller knows about itself that a host cannot — which binary is asking, which build produced it, what the caller's own terminal can render, and which desktop helpers the caller can actually deliver through — travel as parameters rather than being guessed at from the host's process. A host that is not running cannot answer this at all, which is the one case a client handles itself: it says so and names `narya doctor`, the command that walks a machine whose host is down. One line stays the HOST's own fact whatever a caller says: the keychain check describes the session the host process runs in, since that is the process that stores and reads a credential. operationId: getDoctorReport parameters: - name: callerVersion in: query required: false schema: type: string maxLength: 128 description: >- The version of the binary ASKING. The walk compares it against the answering host's own, which is what reports a host serving your sessions from a different build than the one on disk. Omitted, the host reports its own version and that comparison cannot fire. - name: callerGeneration in: query required: false schema: type: string maxLength: 128 description: >- The build job that produced the asking binary, when there was one — an extension rebuild stamps it. Reported on the binary line. - name: callerColorProfile in: query required: false schema: type: string maxLength: 32 description: >- What the CALLER's terminal renders, e.g. TrueColor or ANSI256. A daemon's own stdout is a pipe, so a host asked to detect this for a client would report the absence of the client's terminal. Omitted, the host detects its own. - name: callerNotifier in: query required: false schema: type: string maxLength: 128 description: >- The platform notification program the CALLER resolved on its own $PATH, e.g. `notify-send` or `osascript`, or empty for none found. The caller is the process that delivers a banner, so this is a fact about it and not about the answering host: a host started by systemd or launchd carries a minimal PATH and no desktop session, and answering from its own walk reports "no platform notifier on this machine" to a person sitting at one. Omitted entirely — as `narya doctor` run against a host omits it — the host walks its own $PATH. - name: callerSoundPlayer in: query required: false schema: type: string maxLength: 128 description: >- The audio player the CALLER resolved on its own $PATH, e.g. `paplay` or `afplay`, or empty for none found. A fact about the caller for callerNotifier's exact reason: the caller is the process that plays the sound. Omitted, the host walks its own $PATH. responses: '200': description: The health walk, rendered and structured. content: application/json: schema: $ref: '#/components/schemas/DoctorReport' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' components: schemas: DoctorReport: type: object description: >- One health walk over an installation: the aligned text `narya doctor` prints, plus the same lines structured so a caller can gate on them without parsing prose. healthy, failures and `narya doctor`'s exit code are one decision expressed three times, never three that can disagree: healthy is failures == 0, and the command's exit code is its projection. Warnings are compatible with healthy — a warning is something that works today and will bite you later — which is why the counts are carried separately and a stricter consumer can gate on warnings itself. required: - text - version - home - healthy - findings - warnings - failures - checks properties: text: type: string description: >- The walk as `narya doctor` prints it: one aligned name/status/detail line per check, each finding's remedy indented underneath, and a closing verdict. Carried so a client renders the same walk a terminal does rather than re-implementing the layout and drifting from it. version: type: string description: The version the walk reports for the binary it describes. home: type: string description: The resolved narya home directory this walk describes. healthy: type: boolean description: Nothing is broken — no fail-class line. This is what exit 0 means. findings: type: integer minimum: 0 description: Every line that is not ok — warnings plus failures. warnings: type: integer minimum: 0 failures: type: integer minimum: 0 checks: type: array description: Every line of the walk, in the order it was checked. items: $ref: '#/components/schemas/DoctorCheck' examples: - text: | narya doctor — /Users/dev/.config/narya home ok ... no findings version: 1.0.0 home: /Users/dev/.config/narya healthy: true findings: 0 warnings: 0 failures: 0 checks: - name: home status: ok detail: /Users/dev/.config/narya DoctorCheck: type: object description: >- One line of the health walk: what was checked, how it looks, and — when it does not look right — what to do about it. required: - name - status - detail properties: name: type: string description: What was checked, e.g. home, config, store, terminal. status: type: string enum: - ok - warn - fail description: >- ok is a FACT about this installation, never a finding. warn means it works today and will bite you later. fail means it needs fixing now, and is the only class that makes `narya doctor` exit 1. detail: type: string description: What the check found, in one line. remedy: type: string description: >- The command that repairs this finding. Doctor names a repair; it never runs one. Error: type: object description: >- The single error envelope every operation returns. Codes are NRY- followed by four digits and are catalogued in the top-level x-error-catalog extension. required: - code - title - message properties: code: type: string pattern: ^NRY-[0-9]{4}$ description: Machine-readable error code from the NRY catalogue. title: type: string maxLength: 256 description: Short human-readable summary of the error class. message: type: string maxLength: 4096 description: Specific, actionable description of what went wrong. fields: type: object description: Per-field validation problems. additionalProperties: type: string examples: - code: NRY-0002 title: Session not found message: >- No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host. responses: BadRequest: description: Malformed request — invalid parameter, cursor, or JSON body. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Authentication required — a request carrying no valid identity token (NRY-0011). content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: The host failed — including a store that refuses writes (NRY-0012). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation. ````