Ejecuta Narya

Narya se divide en un host y sus clientes. El host posee el almacén, las sesiones y las conexiones con los modelos. En tu propia máquina, un cliente envía un mensaje y lee el resultado por el socket local. Un cliente interactivo inicia un host cuando ningún host responde, y luego lo maneja por la misma API HTTP que cualquier otro cliente.

​

Autentícate en tu organización

---

En tu propia máquina, el host acepta a tu propio usuario del sistema operativo sin autenticación. Autentícate en tu organización para el trabajo que llega a ella más allá de esta máquina: recursos compartidos, los repositorios de GitHub de tu organización, y registrar, cambiar o llamar extensiones. El primer trabajo autenticado en un home reclama el home para tu organización. La persona autenticada pasa a ser dueña del trabajo hecho ahí antes. Después de eso, el host rechaza una solicitud sin token mientras esta máquina no esté autenticada en esa organización. Completa la tabla [identity] en config.toml con los valores que te da tu organización: issuer, jwks_url, auth_url, device_url y client_id. Un host sin issuer o jwks_url rechaza cada token. El host aplica un cambio en [identity] en su siguiente inicio después de que una persona permite el nuevo config.toml en una conversación atendida. Consulta Cuándo entra en vigor un cambio de configuración.

• narya login imprime una URL y un código corto. Abre la URL en cualquier máquina con navegador e ingresa el código.
• narya whoami informa con qué identidad está autenticada esta máquina, sin llamada de red.
• narya logout elimina la autenticación.

Narya guarda los tokens y los renueva cuando expiran. El cliente interactivo y cada comando que habla con el host en ejecución los presentan.

​

El host

---

​

Mantén el host vivo entre inicios de sesión

---

narya daemon install escribe un servicio de inicio de sesión y lo carga: un LaunchAgent en macOS y una unidad de systemd de usuario en Linux. Ambos ejecutan narya host start y lo reinician después de una falla. Narya escribe la unidad con permisos 0600. Define NARYA_HOME dentro de la unidad en lugar de heredar el valor. narya daemon status responde tres preguntas por separado: registrado, cargado y sirviendo. narya daemon uninstall elimina la unidad y nada más. Tus sesiones, tu almacén y tu configuración se mantienen. El host y cada sesión dentro de él sobreviven a una terminal cerrada. Un narya -p posterior se conecta al host en ejecución en lugar de abrir el almacén por sí mismo.

​

Sesiones

---

Cada sesión se liga a una ruta de repositorio. Retoma una con narya -s <session-id>, o con narya -p --session <session-id>.

• narya session list lista las sesiones del almacén.
• narya export <session-id> escribe una transcripción en la salida estándar. Elige --format markdown o --format jsonl. Agrega --reasoning y --tool-output para más detalle.
• narya import <file> --repository <absolute path> lee una transcripción de otra herramienta. Define --format claudecode o --format opencode.
• narya session promote <session-id> entrega la sesión al host en ejecución, así que una pregunta de permiso posterior en ella se rechaza y se registra.
• narya session share <session-id> copia la sesión al home de tu organización. Agrega sync para seguir enviando las entradas posteriores.

​

Compartir una sesión

---

Un recurso compartido copia una sesión al home de tu organización, donde tu equipo la lee. El host enmascara las entradas antes de que salgan de tu máquina. Defines las reglas de enmascaramiento en la tabla [sharing.redaction] de config.toml. Dos campos de la publicación son opcionales:

• expiresAt define cuándo termina el recurso compartido. Sin él, se aplica la ventana del host. Define esa ventana con default_expiry en la tabla [sharing].
• recipients nombra a los colegas para quienes es el recurso compartido. Sin él, el recurso compartido es para toda la organización. Solo el dueño de la sesión puede nombrar destinatarios.

Un 503 con NRY-0029 significa que el host registró el recurso compartido y encoló sus entradas, pero el home de la organización no respondió. El host envía las entradas más tarde. Cada publicación crea un recurso compartido nuevo, así que una segunda publicación de la misma sesión crea un segundo recurso compartido.

• GET /v1/sessions/{sessionId}/share lista los recursos compartidos activos de la sesión que puedes cambiar.
• PUT /v1/shares/{shareId}/recipients cambia para quién es un recurso compartido.
• DELETE /v1/sessions/{sessionId}/share revoca todos los recursos compartidos de la sesión y borra la copia en el home de la organización. Un 503 con NRY-0029 significa que la copia sigue allí. Envía la solicitud otra vez cuando el home responda.
• GET /v1/shares en el home de la organización lista los recursos compartidos que puedes leer allí.

Un recurso compartido revocado no vuelve. Para compartir la sesión otra vez, publícala otra vez, lo que crea un recurso compartido nuevo.

​

Ejecutar una sesión en un entorno

---

Un entorno es un contenedor que el host aprovisiona para tus sesiones. Una sesión que no nombra ningún entorno se ejecuta en la máquina del host. El host aprovisiona entornos solo cuando la variable de entorno NARYA_SANDBOX_IMAGE nombra la imagen que se ejecuta. El host los ejecuta en Docker Engine 23 o posterior, y la imagen ya debe estar en el daemon de Docker. Agrega --container a narya o a narya -p para abrir una nueva conversación en un contenedor propio, conversation-<sessionId>. Por la API, define container como true en POST /v1/sessions. Este contenedor, y cada contenedor de un home alojado, se detiene después de 15 minutos sin uso, conserva sus archivos y vuelve a arrancar con el siguiente mensaje. Archivar la conversación elimina el contenedor.

• POST /v1/environments crea un entorno. Solo id es obligatorio. setupScript se ejecuta una vez dentro del nuevo entorno. repository nombra un repositorio que tu organización seleccionó en la GitHub App de Narya, como owner/name, y el host lo clona en el entorno.
• GET /v1/environments lista tus entornos, y GET /v1/environments/{environmentId} lee uno.
• DELETE /v1/environments/{environmentId} destruye un entorno.

Para ejecutar una sesión en un entorno, pon el id del entorno en el campo environment de POST /v1/sessions. Una creación es idempotente en id. Cuando envías un id que ya creaste, el host responde 200 con ese entorno. No aprovisiona nada y no ejecuta ningún script de configuración. Cuando el script de configuración termina, el host detiene cada proceso que el script dejó en ejecución. Un proceso que salió del grupo de procesos del script, por ejemplo con setsid, y sigue en ejecución hace fallar la configuración. Cuando el script de configuración falla o supera el límite de tiempo del host, el entorno queda unusable. Su campo setup lleva el resultado y la salida del script. Una sesión no puede ejecutarse en un entorno unusable. Destrúyelo y luego créalo otra vez con un script corregido.

​

Un home que Lerian aloja

---

Lerian también ejecuta Narya como un home alojado, uno por cada organización. El home alojado sirve la misma API del host. Cada sesión allí se ejecuta en un contenedor.

• Una sesión que no nombra ningún environment, clone ni container recibe su contenedor, conversation-<sessionId>, en su primer turno. Con clone, o con container definido como true, la sesión recibe su contenedor al crearse.
• Define clone en POST /v1/sessions para clonar un repositorio en el contenedor cuando se crea la sesión. Nombra un repositorio que tu organización seleccionó en la GitHub App de Narya, como owner/name. La sesión trabaja en su propia rama, narya/conversation-<sessionId>.
• Después del clon, el .narya/setup.sh del repositorio se ejecuta una vez en el contenedor. setupScript lo reemplaza. Un clon o una configuración que falla no abre ninguna sesión.
• La ruta repository de una sesión es relativa al workspace del home.
• Archivar la conversación elimina su contenedor, su clon y su rama. Una rama que la sesión envió sigue en GitHub.

Cuando la configuración de un repositorio tiene éxito, el home guarda una copia de ese contenedor, llamada instantánea. El siguiente contenedor del mismo repositorio y la misma configuración parte de la instantánea, en la rama predeterminada, y no ejecuta ninguna configuración. El home descarta una instantánea después de 24 horas, o cuando cambia el .narya/setup.sh del repositorio, y toma una nueva en la siguiente configuración exitosa. Si la configuración edita un archivo que git rastrea, el home no guarda ninguna instantánea. Un home alojado rechaza estas solicitudes con 422:

• Una instalación de paquete. Registra una extensión en una dirección HTTPS en su lugar.
• Un inicio de sesión subscription.
• Una respuesta de confianza. Una sesión allí toma la confianza de su contenedor.
• Un worktree en una sesión nueva.

​

Checkpoints y rewinds

---

Dentro de un repositorio git, Narya registra puntos de restauración de tu árbol de trabajo en un repositorio git paralelo junto a tu checkout. Tu propio historial de git nunca cambia. Ningún temporizador elimina un checkpoint. Fuera de un repositorio git, Narya no registra ninguno, y rechaza un rewind de los archivos. Un rewind mueve una sesión hacia atrás en la conversación, en los archivos o en ambos. Indica el alcance, porque no tiene valor predeterminado. Antes de que un rewind mueva archivos, Narya registra el árbol tal como está, así que el estado que dejas se vuelve un punto de restauración propio.

​

Salud y reparación

---

narya doctor recorre la instalación e informa lo que encuentra:

• el directorio home y la configuración
• el host y el almacén
• las sesiones, los trabajos de paquetes y los servidores de herramientas
• las credenciales
• el binario y la terminal

No repara nada. Cada hallazgo nombra el comando que lo corrige. narya repair <session-id> es la salida de una cuarentena. Al iniciar, Narya recupera cada sesión que un apagado no limpio dejó en ejecución, y pone en cuarentena la que no puede reproducir. Este comando reintenta esa recuperación. Agrega --retire para archivar la sesión en su lugar, con su transcripción conservada.

​

Retención

---

Narya elimina los eventos de un turno después de que el turno termina, y la transcripción conserva el turno. Narya conserva todo lo demás hasta que indiques otra cosa. Define una antigüedad máxima por clase bajo [retention] en config.toml.

• narya retention status informa qué eliminaría un barrido.
• narya retention run hace el barrido.
• narya purge <session-id> --yes elimina una sesión y su transcripción. Lo rechaza mientras la sesión tenga un recurso compartido activo, así que revoca el recurso compartido antes.

narya repair, narya retention y narya purge abren el almacén por sí mismos, así que se niegan mientras un host se ejecuta. Detenlo primero con narya host stop.