> ## 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. # Describe the host process > Returns the host's version, uptime, mode and store path. This is the handshake operation clients call first. There is no shutdown operation — host lifecycle belongs to the daemon manager, outside this contract. ## OpenAPI ````yaml /en/openapi/v3-current/narya.yaml get /v1/host 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 runs on your machine and serves this API over a Unix socket in your Narya home. Narya creates the socket owner-only, and file permissions are the whole authorization. There is no password, no token and no TLS. The terminal client and the one-shot command that Lerian ships drive this API, and a client you write drives the same one. Results never arrive on the response of the request that caused them. 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, message, and fields on 422. Codes are NRY- followed by four digits. A paged list answers items, limit and a nextCursor when more remains. Cursors are opaque. servers: [] security: [] 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: 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: 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. paths: /v1/host: get: tags: - host summary: Describe the host process description: >- Returns the host's version, uptime, mode and store path. This is the handshake operation clients call first. There is no shutdown operation — host lifecycle belongs to the daemon manager, outside this contract. operationId: getHost responses: '200': description: Host metadata. content: application/json: schema: $ref: '#/components/schemas/Host' '500': $ref: '#/components/responses/InternalServerError' components: schemas: Host: type: object description: The host process's identity and operating mode. required: - version - uptimeSeconds - mode - storePath properties: version: type: string description: The host binary's version. uptimeSeconds: type: integer minimum: 0 description: Seconds since the host started. mode: type: string enum: - local description: >- How the host serves this API. `local` names the Unix socket in the Narya home, which is the only transport the host listens on. storePath: type: string description: Absolute path of the local store. pid: type: integer minimum: 1 description: >- The serving process's own id, so a client can cross-check the machine's host registration file against the host that actually answers. That file is a claim written by a process which may be long dead, and its pid is the part that rots: the operating system hands a dead host's number to an unrelated live program, and a client trusting the file alone would report a host as serving when nothing is. Optional because a host older than this field cannot answer it; absent means the cross-check cannot be made, which is not the same as a mismatch. signIns: type: array description: >- Sign-ins the host is waiting on a PERSON to complete right now — an OAuth-protected tool server whose authorization page nobody has visited yet. Present on this operation, rather than only on the per-server tool-server readout, because this is the cheap handshake every client already polls: the URL has to reach whoever is at a terminal within seconds of the host asking for it, and a client cannot be asked to ping every tool server to discover that somebody is being waited on. Empty or absent means nobody is waiting. items: $ref: '#/components/schemas/SignInWaiting' diagnostics: type: array description: >- What went wrong while this host loaded, in the order it was discovered: a config key nothing reads, an [extensions] tie-break naming a slot no installed package claims, a package whose manifest could not be read and whose hooks were therefore skipped. Every entry is non-fatal BY CONSTRUCTION — anything fatal fails composition and the process never starts, so there is no severity to carry and no client decision to make about one. Host-scoped, not session-scoped: these are facts about the process, settled once before it served anything and unchanged for its whole life, which is why they ride the handshake rather than a session's own response. A client shows them once per connection, because the host that a shell spawns has its stderr on /dev/null and every interactive client covers the terminal the operator would otherwise read them on. Empty or absent means the host loaded cleanly. Bounded on the host side: at most 64 lines of at most 512 runes each are retained, with overflow announced in the final line, so a loader gone wrong cannot bloat every handshake. The host's own stderr always carries the full text. maxItems: 64 items: type: string maxLength: 512 examples: - version: 1.0.0 uptimeSeconds: 86400 mode: local storePath: /Users/dev/.config/narya/narya.db SignInWaiting: type: object description: >- One tool server sign-in waiting on a person: the page to open, when the host started waiting, and when it stops. The wait is on a HUMAN timescale and is deliberately not the connection attempt's own ceiling — a handshake bound measured in seconds is right for a socket and absurd for somebody opening a browser and passing MFA. required: - server - url - since - expiresAt properties: server: type: string description: The tool server this sign-in belongs to. url: type: string format: uri description: >- The authorization page a person must open. The host is listening on the loopback redirect that page comes back to, so completing it in any browser on this machine connects the server — no restart, and no further command. since: type: string format: date-time description: When the host started waiting for this sign-in. expiresAt: type: string format: date-time description: >- When this sign-in window closes. After it, the server goes down with "nobody completed the sign-in" as its reason and is asked again at most once per window. examples: - server: github url: https://github.test/login/oauth/authorize?client_id=narya&state=b7c1 since: '2026-08-14T09:12:00.000Z' expiresAt: '2026-08-14T09:17:00.000Z' 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. fields appears only on 422 validation errors, mapping each offending property to its problem. 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. Present on 422 only. 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: InternalServerError: description: The host failed — including a store that refuses writes (NRY-0012). content: application/json: schema: $ref: '#/components/schemas/Error' ````