> ## 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. # The host API > One host, one HTTP contract over a Unix socket. Every Narya client drives the same API, and you can write your own against it. Narya runs coding agents behind one HTTP API. One long-lived host on your machine does the work, and every client drives that one API. The API has an OpenAPI 3.1 document. Lerian generates the host's server and its own Go client from this document. Three kinds of client speak it. The terminal client that Lerian ships opens an interactive session. The one-shot command `narya -p` runs one turn for a pipeline. A client you write drives the same operations, with no sign-in step in front. ## What the host owns *** * **Sessions**: durable conversations, each bound to one repository path. * **Lanes**: the parallel tracks inside a session. * **Checkpoints and rewinds**: restore points of your working tree, and the moves back to them. * **The store**: the database that holds the sessions and the decisions. The host takes its lock. * **Model connections**: the host calls the model supplier with your credential. * **Schedules**: prompts on the host's clock, under a spend ceiling. * **Workflows**: JavaScript programs that orchestrate agents. * **Monitors**: long-running commands beside a session, whose output reaches the conversation. * **Permission asks**: the questions in front of a tool call, and the answers you give back. ## Reach the host *** The host listens on 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. Any process that runs under your account holds the full API. The socket is `narya.sock` inside your Narya home, which is `~/.config/narya` by default. Set `NARYA_HOME` to move it. Over that socket the host speaks HTTP/1.1 and answers JSON with camelCase fields. The authority in the URL carries nothing, so any name works there. ```bash theme={null} curl --unix-socket ~/.config/narya/narya.sock http://narya/v1/host # Answers one JSON object about the running host. ``` When a host runs, the one-shot command is itself a client of this API. A one-shot run that finds no host opens the store itself, when no other Narya process holds it. ## Results arrive on the event stream *** A result never comes back on the request that caused it. A message answers `202` with a turn id. Everything that turn produces reaches you on `GET /v1/events` as server-sent events. A frame is an `id:` line, then a `data:` line, then a blank line. The `data` line carries one JSON envelope. Its `type` field says which event this is: a text delta, a tool call, a permission ask, a finished turn. A client reads one shape and branches on `type`. Send a `Last-Event-ID` header to resume where you stopped. A cursor that names an event newer than the store answers `409`. A consumer too slow to keep up loses its own connection, and every other client keeps streaming. Two query parameters narrow the stream. `sessionId` keeps one session. `hostEvents=true` adds the events that belong to no session, and it applies only beside `sessionId`. `narya -p --json` prints these same envelopes, one per line. A pipeline and a client read one format. See [Automation and CI](/en/narya/automation-and-ci). ## One shape for lists and errors *** A paged list answers a cursor envelope: `items`, `limit` and a `nextCursor` when more remains. Cursors are opaque, and the API offers no offset paging. The store is append-heavy, so an offset shifts under a concurrent write. One error envelope: `code`, `title` and `message`, plus `fields` on a `422`. A code is `NRY-` and four digits. The [error list](/en/reference/narya/host-api-error-list) names each code and what to do about it. ## Read the reference *** Narya host API overview: transport, streaming, envelopes, and every operation. Every code the host answers with, what triggers it, and the way out.