Skip to main content
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 a token of its own.

​
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 the socket carries no TLS. Every request carries a bearer token from the identity provider in your [identity] settings. The host checks the signature, the issuer, the expiry, and the person and organization the token names. A request with no valid token gets 401 with NRY-0011. A caller whose role lacks the permission an operation needs gets 403 with NRY-0028. An operation that declares another security scheme also accepts that credential: the event stream accepts a registered extension’s signed request. The shipped clients present the token that narya login stored. 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.
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.

​
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 names each code and what to do about it.

​
Read the reference

Narya host API overview

Narya host API overview: transport, streaming, envelopes, and every operation.

Narya host API error list

Every code the host answers with, what triggers it, and the way out.