Guía de usuario — Shell Sentinel

Introducción

Shell Sentinel es una aplicación de terminal que mantiene una sesión SSH/SFTP persistente contra un servidor remoto y ofrece un asistente conversacional que traduce tus instrucciones en acciones seguras y trazables.

Requisitos

• Terminal compatible con color (ideal xterm-256color).
• Python 3.10 o superior.
• Acceso a un servidor con SSH/SFTP habilitado.

Instalación

1. Crear entorno virtual:

python3 -m venv .venv
source .venv/bin/activate

2. Instalar dependencias:

make install

Configuración de idioma

La aplicación detecta el idioma con SMART_AI_SYS_ADMIN_LOCALE. Si no está definida, usa el locale del sistema (por defecto inglés).

export SMART_AI_SYS_ADMIN_LOCALE=es   # Español
export SMART_AI_SYS_ADMIN_LOCALE=en   # Inglés
export SMART_AI_SYS_ADMIN_LOCALE=de   # Alemán

Inicio de la aplicación

make run

Aparece una pantalla de bienvenida retro que se cierra sola a los 5 segundos o cuando presionas cualquier tecla.

Interfaz

• Panel principal: muestra la conversación en Markdown.
• Área de entrada: editor multilínea; por defecto envías con Ctrl+S.
• Footer: indica estado SSH, proveedor/modelo activo y si el agente está pensando.

Comandos básicos

Los comandos están disponibles en inglés, español y alemán.

• /connect <host> <user> <password|key_path> [puerto] — abre la sesión (puerto 22 por defecto).
• /disconnect — cierra la conexión activa.
• /help — muestra el resumen de comandos.
• /status — expone el estado del agente, proveedor y modelo.
• /exit — abre el diálogo de confirmación antes de salir.

Uso del asistente IA

Escribe instrucciones en lenguaje natural. Si no es un comando slash, el agente Strands la interpretará. Ejemplos:

• Listar los procesos que consumen más CPU
• Subir /tmp/script.sh a /home/ubuntu/bin/script.sh

El asistente reutiliza la sesión SSH/SFTP para ejecutar comandos o transferir archivos y deja rastro en los logs.

Configuración adicional

• conf/app_config.json define estilos, mensajes y atajos mediante claves como {{ui.output_panel.title}}, resueltas según el locale.
• Las traducciones viven en conf/locales/<idioma>/strings.json. Añade nuevas cadenas con _("clave") y crea entradas para cada idioma soportado.
• conf/agent.conf controla el proveedor LLM, herramientas y timeouts.
  Copia conf/agent.conf.example antes de modificarlo.
  Si usas LM Studio, arranca el servidor con lms server start; para Cerebras exporta CEREBRAS_API_KEY o define api_key_env y aprovecha el SDK oficial con streaming SSE.
  Ajusta remote_command.max_output_chars para limitar la salida que verá el agente.

Solución de problemas

• Colores incorrectos: revisa TERM y cambia a xterm-256color.
• El asistente no responde: comprueba conf/agent.conf, credenciales y logs/app.log.
• Mensaje "No hay una conexión SSH activa": ejecuta /connect antes de pedir acciones remotas.

Recursos adicionales

• Manual de colaboración: políticas clave sobre documentación, localización y ciclos de lanzamiento.
• Visión del producto: arquitectura, stack principal y responsabilidades operativas.