Skip to main content
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

1

Start the host

Run narya host start. The host takes the store lock and listens on the socket inside your Narya home directory.
2

Check it

Run narya host status. It reports whether a host runs and the state of each of its tool servers.
3

Stop it

Run narya host stop. The host finishes the requests in flight, then releases the store lock.

​
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.
narya daemon install is the only command that writes a service unit. Nothing else in Narya writes one.

​
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.

​
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. A rewind always branches and never deletes. Narya first records the tree as it stands, so the state you leave becomes a restore point of its own.

​
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.