Run Narya

Narya splits into a host and its clients. The host owns the store, the sessions and the model connections. A client sends a message and reads the result over the local socket. An interactive client starts a host when no host answers, and then drives it over the same HTTP API as every other client.

​

Sign in to your organization

---

Set the [identity] table in config.toml with the values your organization gives you: issuer, jwks_url, auth_url, device_url and client_id. A host missing issuer or jwks_url refuses every request.

• narya login prints a URL and a short code. Open the URL on any machine with a browser, and enter the code.
• narya whoami reports who this machine is signed in as, with no network call.
• narya logout removes the sign-in.

Narya keeps the tokens and refreshes them when they expire. The interactive client and every command that talks to the running host present them. A narya -p run with no host running needs no sign-in.

​

The host

---

​

Keep the host alive across logins

---

narya daemon install writes a login service and loads it: a LaunchAgent on macOS, and a user systemd unit on Linux. Both run narya host start and restart it after a failure. Narya writes the unit with 0600 permissions. It sets NARYA_HOME inside the unit rather than inheriting the value. narya daemon status answers three questions separately: registered, loaded and serving. narya daemon uninstall removes the unit and nothing else. Your sessions, your store and your configuration stay. The host and every session in it survive a closed terminal. A later narya -p attaches to the running host rather than opening the store itself.

​

Sessions

---

Each session binds to one repository path. Resume one with narya -s <session-id>, or with narya -p --session <session-id>.

• narya session list lists the sessions in the store.
• narya export <session-id> writes one transcript to standard output. Choose --format markdown or --format jsonl. Add --reasoning and --tool-output for more detail.
• narya import <file> --repository <absolute path> reads a transcript from another tool. Set --format claudecode or --format opencode.
• narya session promote <session-id> hands the session to the running host, so a later permission prompt in it is refused and recorded.
• narya session share <session-id> copies the session to your organization’s home. Add sync to keep sending later entries.

​

Share a session

---

A share copies a session to your organization’s home, where your team reads it. The host redacts the entries before they leave your machine. You set the redaction rules in the [sharing.redaction] table of config.toml. Two fields of the publish are optional:

• expiresAt sets when the share stops. Without it, the window of the host applies. Set that window with default_expiry in the [sharing] table.
• recipients names the colleagues that the share is for. Without it, the share is for the whole organization. Only the owner of the session can name recipients.

A 503 with NRY-0029 means that the host recorded the share and queued its entries, but the organization’s home did not answer. The host sends the entries later. Each publish creates a new share, so a second publish of the same session creates a second share.

• GET /v1/sessions/{sessionId}/share lists the live shares of the session that you can change.
• PUT /v1/shares/{shareId}/recipients changes who a share is for.
• DELETE /v1/sessions/{sessionId}/share revokes every share of the session and deletes the copy at the organization’s home. A 503 with NRY-0029 means that the copy is still there. Send the request again when the home answers.
• GET /v1/shares on the organization’s home lists the shares that you can read there.

A revoked share does not come back. To share the session again, publish it again, which creates a new share.

​

Run a session in an environment

---

An environment is a separate machine that the host provisions for your sessions. A session that names no environment runs on the machine of the host. The host provisions environments only when the NARYA_SANDBOX_IMAGE environment variable names the image to run.

• POST /v1/environments creates an environment. Only id is required. setupScript runs once inside the new environment. repository names a repository that your organization selected in the Narya GitHub App, as owner/name, and the host clones it into the environment.
• GET /v1/environments lists your environments, and GET /v1/environments/{environmentId} reads one.
• DELETE /v1/environments/{environmentId} destroys an environment.

To run a session in an environment, put the environment id in the environment field of POST /v1/sessions. A create is idempotent on id. When you send an id that you already created, the host answers 200 with that environment. It provisions nothing and runs no setup script. When the setup script fails or runs past the time limit of the host, the environment is unusable. Its setup field carries the outcome and the output of the script. A session cannot run in an unusable environment. Destroy it, then create it again with a corrected script.

​

Checkpoints and rewinds

---

Narya records restore points of your working tree in a shadow git repository beside your checkout. Your own git history never changes. No timer removes a checkpoint. A rewind moves a session back across the conversation, the files, or both. Name the scope, because it has no default.

​

Health and repair

---

narya doctor walks the installation and reports what it finds:

• the home directory and the configuration
• the host and the store
• the sessions, the package jobs and the tool servers
• the credentials
• the binary and the terminal

It repairs nothing. Each finding names the command that fixes it. narya repair <session-id> is the way out of a quarantine. At start, Narya recovers each session an unclean shutdown left running, and quarantines one it cannot replay. This command retries that recovery. Add --retire to archive the session instead, with its transcript kept.

​

Retention

---

Narya keeps everything until you say otherwise. Set a maximum age per class under [retention] in config.toml.

• narya retention status reports what a sweep would remove.
• narya retention run performs the sweep.
• narya purge <session-id> --yes removes one session and everything under it.

narya repair, narya retention and narya purge open the store themselves, so they refuse while a host runs. Stop it first with narya host stop.