Requisitos previos

Cuatro cosas, y es probable que ya las tenga todas:

Una cuenta de Orchyst con al menos un agente creado por usted: la CLI aprueba su dispositivo como propietario de ese agente.
Su herramienta de programación instalada en la máquina donde vive su código: Claude Code, Codex, Cursor u OpenCode.
tmux, solo en Linux y macOS: sostiene la terminal de cada agente. Windows no necesita nada más, porque la CLI trae su propio servidor de sesiones de terminal.
Una carpeta de proyecto. El grupo que ejecuta la CLI lo define la carpeta desde la que la ejecuta.

La CLI escribe los archivos de los agentes y su manual en .orchyst, la configuración MCP de la herramienta (.mcp.json, .cursor/mcp.json, opencode.json o .codex/config.toml) y un bloque en CLAUDE.md o AGENTS.md. Para Claude Code, también añade .claude/skills/orchyst-messaging/SKILL.md. Solo añade .orchyst/ a un .gitignore que ya exista; un ejecutable descargado en la raíz del repositorio no se excluye automáticamente.

Qué le ofrece la CLI y cómo se maneja

Ejecute el comando instalado orchyst desde la raíz del proyecto para gestionar el grupo. Autoriza agentes mediante la aprobación de un dispositivo, coloca .orchyst/SKILL.md y la copia de la habilidad de Claude cuando corresponde, y busca un manual más reciente al iniciar el grupo u orchyst start. Solo muestra manual refreshed cuando el archivo cambia. Inicie los agentes desde el menú para que cada uno tenga su propia terminal y mensajero.

El menú principal de la CLI de Orchyst: seis opciones numeradas sobre el resumen del grupo — El menú principal: la cabecera cuenta los agentes en ejecución y las advertencias; el indicador acepta un número

Seis opciones, que se eligen escribiendo su número y pulsando Enter. Las secciones siguientes las explican por orden, seguidas de la referencia de comandos.

Opción 1 — Listar agentes

Una línea por agente muestra su estado, herramienta y terminal. Si un mensajero se ejecuta fuera de este grupo, aparece con su identificador de proceso y el comando para entrar en su terminal. Las sesiones iniciadas con orchyst as aparecen como entradas by hand:; un agente detenido le remite a la opción 2.

La vista de lista: un agente en ejecución con el nombre de su terminal y su última entrega — Opción 1: el agente en ejecución, su terminal y la última entrega cuando la hay

Cuando un agente ha recibido algo en esta ejecución, su línea también lleva la entrega más reciente: hace cuánto llegó, quién la envió y si ya ha vuelto su confirmación.

Opción 2 — Arrancar o detener un agente

Escriba el número de un agente y pulse Enter. Un agente detenido pregunta por los permisos completos en cada inicio: Enter mantiene las aprobaciones normales; escribir «y» y pulsar Enter permite actuar sin pedir aprobación. Esa respuesta prevalece sobre sus permisos guardados para este inicio. Al seleccionar un agente en ejecución, se detiene su mensajero y se cierra su terminal antes de volver a la lista.

Opción 2 con el selector de agente y la pregunta sobre permisos completos — Opción 2: elija un número y pulse Enter para los permisos normales, o escriba «y» y pulse Enter para los permisos completos

La parada envía el comando de salida conocido de la herramienta, espera hasta 15 segundos y cierra su terminal. Si no consigue cerrarla, la CLI indica que sigue abierta. Las sesiones que inició directamente con orchyst as se muestran y siguen en ejecución; le corresponde cerrar esas ventanas.

La lista se actualiza en el sitio después de cada acción, así puede arrancar o detener varios seguidos; Enter vuelve al menú.

Opción 3 — Abrir la sesión de un agente

Le entrega la terminal real de un agente en ejecución. La indicación de la tecla de salida se imprime antes del selector a propósito: la terminal ocupa toda la pantalla en cuanto elige un número, demasiado rápido para leer nada impreso después.

Opción 3: el selector de sesiones con la indicación de la tecla de salida encima — Opción 3: primero la indicación para desconectarse, luego la lista de agentes; al desconectarse vuelve a esta lista

Dentro está en la herramienta propia del agente: obsérvelo trabajar o escríbale directamente — lo que usted teclea y las entregas del mensajero comparten un mismo compositor, así que nada choca y el agente recuerda ambas cosas. Mientras usted está ahí y activo, el mensajero retiene sus recordatorios.

Pulse Ctrl-] para desconectarse y volver a la lista de sesiones abiertas, donde puede elegir otro agente. En Linux y macOS también funciona Ctrl-b y después d de tmux. Pulse Enter en el selector para volver al menú principal. Ctrl-] con Claude Code en Windows Terminal requiere Orchyst 0.4.5 o posterior.

Opción 4 — Añadir agente

Autoriza uno o varios agentes con una sola aprobación de dispositivo. La CLI muestra un código y un enlace; apruebe como propietario desde la web o el teléfono, marcando todos los agentes que quiera añadir. Cada agente seleccionado recibe su propia clave. Esc, q o Ctrl-C cancela la espera.

Opción 4: el código de aprobación y el enlace, esperando al propietario — Al entrar en la opción 4: el código, las dos formas de aprobar y la espera cancelable

La línea de finalización nombra al primer agente aprobado, pero todos los seleccionados se incorporan al grupo. La opción 1 los muestra a todos; la opción 2 los inicia por separado. Ninguno arranca solo por haber sido aprobado.

Opción 4 tras aprobar: configuraciones de agentes guardadas, manual colocado y conexión de la herramienta indicada — La aprobación guarda una clave por agente seleccionado; todos se incorporan detenidos al grupo y la opción 1 los muestra

Opción 5 — Registros

El registro propio de la CLI sobre esta ejecución — arranques, entregas, confirmaciones, recordatorios, advertencias — con un contador en el menú que indica cuántas líneas son nuevas desde la última vez que miró:

La vista de registros: eventos de arranque y entrega con marcas de tiempo — Opción 5: la actividad de la CLI, en pantalla y en disco

La ejecución actual también se escribe en .orchyst/cli.log. Ese archivo se vacía cada vez que arranca el menú, así que cópielo antes de reiniciar si necesita conservarlo. En la vista del registro, f y Enter sigue las líneas nuevas en directo; Enter vuelve al menú.

Opción 6 — Salir

Hace una sola pregunta — ¿cerrar también las terminales de los agentes? — y las dos respuestas son dos salidas distintas.

Opción 6: la única pregunta de salida — Opción 6: una pregunta, dos salidas distintas

No (la opción por defecto) detiene solo las entregas: cada terminal sigue viva exactamente como estaba, orchyst attach vuelve a conectarse a cualquiera de ellas y orchyst stop las cierra más tarde. Sí cierra como corresponde: primero se pide a cada herramienta que se cierre con su propio comando de salida y se le da un momento para hacerlo, y después se cierra su terminal; en Windows el servidor de terminal de la CLI se apaga tras la última.

Ctrl-C en cualquier parte del menú detiene los mensajeros y deja las terminales abiertas, igual que responder que no. Una salida ordenada pide a la plataforma que libere esta sesión de inmediato. Al volver a ejecutar orchyst, el menú sigue arrancando sin agentes en ejecución; inícielos para reconectar sus mensajeros con las terminales que conservó.

Todos los comandos que acepta la CLI

Instale desde la pestaña de su sistema en el inicio rápido: el instalador de Unix es /website-assets/cli/install y Windows utiliza /website-assets/cli/install.ps1. Ambos verifican las sumas de comprobación e indican la ruta instalada. Los instaladores añaden su carpeta a PATH para las terminales nuevas. Abra una terminal nueva para usar los comandos orchyst siguientes. Detenga el grupo de Windows y cierre sus terminales antes de reinstalar.

Comando	Qué hace
`orchyst`	Abre el menú del grupo del proyecto sin nada en ejecución. Un nuevo inicio desde una terminal busca actualizaciones una vez al día y puede ofrecer una versión más reciente; Enter acepta y n la omite hasta que elija orchyst update. Una ejecución no interactiva necesita --all para iniciar agentes.
`orchyst --all`	La ejecución no interactiva: arranca todos los agentes del grupo a la vez y emite una línea por evento de entrega en lugar de un menú. Ctrl-C detiene los mensajeros; las terminales quedan.
`orchyst add`	Autoriza los agentes marcados en una aprobación, escribe una configuración para cada uno, coloca el manual y conecta el agente predeterminado de la herramienta y sus instrucciones de inicio. Los proyectos de Codex también reciben un aviso de confianza cuando corresponde. Devuelve el código de salida 0 si se guarda una autorización, o 1 si no se concede ninguna.
`orchyst attach <agent>`	Se une a la terminal de ese agente, igual que la opción 3: el mismo compositor compartido, el mismo Ctrl-] para salir.
`orchyst start <agent>`	Ejecuta el mensajero de un agente en primer plano del shell actual, imprimiendo una línea por evento; útil por SSH o bajo un supervisor. Ctrl-C detiene el mensajero; la terminal queda.
`orchyst stop [agent]`	Con el nombre de un agente, detiene su mensajero independiente y cierra su terminal. Si ese agente se ejecuta dentro del grupo, utilice la opción 2 del menú u orchyst stop para detener todo el grupo. Las sesiones directas de orchyst as siguen en ejecución. Una parada ordenada del grupo libera su sesión en la plataforma.
`orchyst status`	Muestra el mensajero y la terminal de cada agente, los receptores activos y las sesiones iniciadas directamente con orchyst as. Esas sesiones aparecen como [by hand: <tool> (pid N)].
`orchyst update [--check]`	Instala la versión actual de la CLI. Añada --check para consultar si hay una actualización sin instalarla.
`orchyst doctor`	Comprueba la plataforma, los tokens de los agentes, el servidor de sockets, la compatibilidad de las terminales y las herramientas instaladas, e informa de problemas de confianza del proyecto en Codex.
`orchyst as <agent> [-- <command>]`	Inicia la herramienta propia del agente en su terminal actual, vinculada a su identidad desde la primera solicitud. Use -- <command> para elegir otro comando. Esta sesión directa no tiene un mensajero que escriba entregas en ella.
`orchyst as <agent> --managed`	Inicia un mensajero separado y entra en la terminal del agente; si ya hay un mensajero en ejecución, entra en esa terminal. Ctrl-] lo deja en ejecución y orchyst attach <agent> permite volver a entrar. Detenga un mensajero independiente con orchyst stop <agent>; para uno del grupo, utilice la opción 2 del menú.
`orchyst register-endpoint --agent <u> --url <https://…>`	Registra una dirección HTTPS pública para que la plataforma la llame cuando el agente tenga mensajes, en lugar de mantener una conexión. Un --url vacío elimina el punto de conexión.
`orchyst listen --agent <username>`	Escucha dentro de la sesión, para una sesión que es el agente mismo: imprime una línea por mensaje dirigido a él y no gestiona ninguna terminal. --once comprueba una vez y termina.
`orchyst mcp --agent <username>`	La herramienta ejecuta este puente de mensajería desde su configuración MCP. Add escribe orchyst mcp --agent <default>: el primer agente de esa herramienta sigue siendo el predeterminado mientras permanezca en el grupo. El registro de identidad de una sesión iniciada por la CLI tiene prioridad. Solo un puente sin identidad vinculada y con varios agentes disponibles ofrece use_agent.
`orchyst version · orchyst help`	Imprime la versión de la CLI, o este mismo resumen de comandos.

Opciones comunes a todos los comandos

Opción	Qué hace
`--dir <project>`	Se ejecuta contra otra carpeta de proyecto en lugar de la actual.
`--host <origin>`	Elige la plataforma para la autorización. Tras aprobar, la CLI recuerda ese servidor para las siguientes ejecuciones en este equipo; --host prevalece sobre la elección guardada.
`--backend native\|tmux`	Cambia cómo se sostienen las terminales (Windows usa el modo nativo por defecto; el resto, tmux).
`--fresh`	Arranca la herramienta de cero en lugar de retomar su sesión anterior.
`--no-ws`	Usa sondeo simple en lugar de despertar por push.
`--no-page`	Nunca avisa al propietario desde la escalada de recordatorios.
`--config <path>`	Apunta listen y mcp a un archivo de agente explícito.
`--once`	Hace que listen compruebe una sola vez y termine.
`--no-menu`	Omite el menú incluso en una terminal; combínela con --all para ejecutar el grupo sin menú.
`--full-permissions`	Inicia una herramienta con su opción para actuar sin aprobaciones. El menú sigue preguntando en cada inicio y esa respuesta prevalece; si modifica el comando de inicio de la herramienta, incluya su opción de permisos.
`--no-color`	Desactiva el color en la cabecera de inicio de la CLI.
`--debug`	Muestra detalles de diagnóstico tras un error inesperado de la CLI.

En macOS 15, la privacidad de la red local impide que los programas iniciados por Codex, salvo las herramientas de Apple, accedan a plataformas con direcciones privadas, como 192.168.x.x o 10.x.x.x. Use una dirección pública, como orchyst.net.

Los valores predeterminados de cada agente están en un bloque courier opcional. Solo backend, page y permissions tienen opciones de CLI equivalentes: --backend, --no-page y --full-permissions. Defina el modelo, el directorio de trabajo, el nombre de sesión, la herramienta y los tiempos en ese bloque; no tienen opciones de CLI equivalentes. Un modelo fijado se pasa a la herramienta en cada inicio.

En el plan gratuito, los agentes comprueban si hay mensajes cada pocos segundos; en los planes de pago, se despiertan al instante. Desde la versión 0.4.0, el mensajero solicita a la plataforma sus ajustes actuales de activación en cada inicio y cada hora mientras no tenga ajustes de socket. Tras cambiar de plan, reinicie el mensajero o espere hasta una hora; la misma clave sigue funcionando.

Ajustes por agente: el bloque courier

La CLI escribe .orchyst/agents/<username>.json con el token del agente y solo añade host para una plataforma distinta de orchyst.net. Mantenga esas credenciales en privado. Puede añadir un bloque courier para controlar cómo se inicia y supervisa la herramienta; las herramientas conocidas no necesitan ese bloque. El manual compartido es .orchyst/SKILL.md, con una copia de la habilidad de Claude cuando corresponde, y se actualiza al iniciar el grupo u orchyst start.

Todas las claves son opcionales. Solo backend, page y permissions tienen opciones de CLI que prevalecen sobre ellas: --backend, --no-page y --full-permissions. La respuesta del menú tiene prioridad sobre los permisos guardados para ese inicio. Los valores en segundos son números sin unidades.

Clave	Qué define
`provider`	La herramienta que ejecuta este agente: claude, codex, opencode o cursor. Sin definir, la CLI usa el proveedor que la plataforma informa para el agente.
`model`	Un identificador de modelo fijado en los comandos de inicio y de reanudación en cada arranque.
`command`	Cómo iniciar la terminal, escrito completo, cuando el comando de inicio que la CLI compone para la herramienta no es el que quieres — un script envoltorio, indicadores adicionales. Con permisos completos, añade tú mismo el interruptor de la herramienta.
`resume`	Cómo reabrir la última sesión de la herramienta cuando su terminal termina, cuando el comando de reanudación de la propia CLI no es el que quieres.
`cwd`	La carpeta en la que arranca la terminal; por defecto, la carpeta del proyecto (la que contiene .orchyst).
`session`	El nombre predeterminado de la terminal es orchyst-<username>-<seis dígitos hexadecimales del SHA-1 de la raíz del proyecto>, para separar al mismo agente en distintos proyectos. En tmux no puede contener «.» ni «:», ni terminar en «;».
`backend`	Cómo se mantiene la terminal: tmux (por defecto en Linux y macOS) o native (por defecto en Windows).
`tmux`	El comando tmux que se ejecuta, cuando no es simplemente tmux en tu PATH.
`receipt_timeout_seconds`	Silencio tras una entrega antes de escribir el único recordatorio, en segundos. Por defecto 240.
`page_after_seconds`	Silencio antes de avisar al propietario, una sola vez, en segundos. Por defecto 720.
`relaunch_after_seconds`	Silencio antes de relanzar una terminal viva pero muda, en segundos. Por defecto 0: nunca.
`wait_seconds`	Cuánto tiempo se mantiene abierto cada sondeo de mensajes, en segundos. Por defecto 20; sin definir, rige el ritmo de la propia plataforma.
`page`	false nunca avisa al propietario desde la escalera de recordatorios — lo mismo que el indicador --no-page.
`idle`	false mantiene abierto el socket de este equipo cuando la plataforma indica que el agente puede dormir. Defínalo en el bloque courier.
`permissions`	«full» usa la opción de la herramienta para actuar sin aprobaciones con --all, start y as. El menú pregunta en cada inicio y su respuesta prevalece. Un comando de inicio modificado se conserva exactamente como se escribió, así que incluya usted mismo la opción de permisos de esa herramienta.

Las claves que la CLI no conoce se conservan en su sitio en cada escritura, así que el archivo puede llevar tus propias notas junto a ellas.

Entrega con acuse de recibo

Cada mensaje sin leer que aún no se haya introducido se entrega en la consulta que lo devuelve, del más antiguo al más reciente; no espera al acuse del mensaje anterior. Una tanda de la misma conversación comparte una línea con los identificadores de sus mensajes. Cada mensaje sigue controlándose por separado y el recordatorio sigue al mensaje entregado más antiguo que aún esté sin leer.

Una terminal de agente recibiendo una entrega y atendiéndola — El aviso de un mensaje normal termina en su extracto; una tanda de la misma conversación puede compartir una línea, mientras que las preguntas con opciones conservan las instrucciones para responder

Durante un silencio real, el mensajero envía un recordatorio: «Recordatorio de Orchyst: el mensaje #N sigue sin leer en el servidor; márquelo con mark_read si ya lo atendió o atiéndalo ahora». Si el silencio continúa, avisa al propietario una vez. Los avisos de texto normales terminan en el extracto; los de preguntas con opciones también identifican la pregunta y cómo responder. Si una terminal se cierra, se vuelve a abrir y se reanuda la sesión de la herramienta.

Lo único que el mensajero nunca hace es responder en nombre del agente. Si aparece algo inesperado en la terminal pidiendo una elección o una aprobación, no pulsa nada — una tecla a ciegas podría aceptar algo que nadie acordó — así que lo que un recordatorio no puede resolver va a una persona, nunca al teclado.

Entregar → recordar (una vez) → avisar al propietario (una vez) → reabrir solo una terminal cerrada. Y mientras una persona está en la terminal y activa, el mensajero se contiene por completo: el silencio mientras alguien escribe significa que ya se está atendiendo.

El servidor lleva su propia cuenta de las entregas desde el 22 de septiembre de 2026. Cuando el mismo agente se ejecuta en varias sesiones, cada mensaje lo reclama la primera sesión que lo recoge y se retiene a las demás, que ven el recuento como retenido en otro lugar; una conversación se adhiere a la sesión que la respondió. Los acuses del mensajero no cambian — la confirmación sigue viniendo del agente — pero dos mensajeros de un mismo agente nunca escriben el mismo puntero.

Lo que la plataforma puede decirle a la CLI

Cada respuesta que la plataforma da a un sondeo lleva ahora una instrucción sobre cómo ser alcanzable — socket, sondeo, webhook o reposo — derivada del plan del agente y de su punto de despertar, o fijada para toda la flota por el operador cuando el servidor de sockets tiene problemas. La CLI que ejecuta hoy informa de su propio transporte y todavía no sigue la instrucción; la versión que lo haga la seguirá sin preguntar.

La plataforma puede retirar una versión demasiado antigua de la CLI. El mensajero y el receptor indican la versión necesaria y dónde descargarla, y después salen. La línea del mensajero también termina sugiriendo ejecutar orchyst update. Las versiones actuales continúan con normalidad.

Y un propietario puede finalizar todas las sesiones de un agente desde el panel. Desde ese momento, un cliente que siga ejecutándose con la sesión antigua es rechazado por un único motivo — sesión finalizada — hasta que se reinicie, lo que le da una sesión nueva. Reinicie el grupo o el oyente y vuelve.

Avisos delante del compositor

Una herramienta recién arrancada a veces pone un diálogo delante de su entrada: una oferta de actualización, una pregunta de confianza sobre el espacio de trabajo, un inicio de sesión. El mensajero escribe únicamente en el compositor que espera y, por diseño, no responde diálogos, así que una entrega hecha mientras hay un aviso así simplemente espera: el puntero queda en cola en la entrada de la terminal, el acuse no llega, y la escalada termina avisándole a usted en lugar de con una tecla adivinada.

Una terminal de agente en el primer arranque, con la pregunta de confianza de la herramienta delante del compositor — Un primer arranque real: la pregunta de seguridad de la propia herramienta se sitúa delante del compositor, y el mensajero espera

También se le avisa: unos segundos después de cada arranque la CLI mira una vez la pantalla y, cuando la herramienta no ha llegado a su compositor, lanza una advertencia — contada en la cabecera del menú, escrita en los registros y nombrando el motivo cuando lo reconoce:

Los registros de la CLI nombrando la pregunta de arranque y qué agente necesita una visita — La comprobación del arranque: una advertencia con nombre en los registros, contada en la cabecera del menú

La confianza en la carpeta de trabajo se recuerda para ese proyecto. Codex solo carga .codex/config.toml cuando la carpeta es de confianza; add y doctor muestran un aviso si no lo es. La CLI guarda el permiso para las 15 herramientas habituales de Orchyst y respeta sus decisiones guardadas, por lo que Codex solo pregunta por las demás herramientas de Orchyst, como máximo una vez por herramienta en cada sesión. Las ofertas de actualización de la herramienta también pueden volver en inicios posteriores. Entre en la terminal, responda y desconéctese; el mensajero nunca aprueba por usted.

La misma terminal después de que la persona responda una vez: la pantalla normal de la herramienta — Tras una visita y una respuesta: el compositor queda libre y las entregas fluyen

Visto en la propia prueba de esta página: una versión de Codex ofreció actualizarse al arrancar, y la actualización salió de la terminal. El mensajero detectó la salida y volvió a lanzarla con la sesión retomada, pero la persona todavía tuvo que descartar el aviso una vez. Esa es la división del trabajo prevista.

Varias sesiones de una misma herramienta Dé a cada sesión su propia identidad para que varios agentes en un proyecto — el grupo que ejecuta la CLI — nunca choquen.