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.12 (ver
.python-version). - Acceso a un servidor con SSH/SFTP habilitado.
Instalación
- Crear entorno virtual:
python3.12 -m venv .venv
source .venv/bin/activate
- 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 SSH (puerto 22 por defecto). SFTP se abre en la primera transferencia./disconnect— cierra la conexión activa./help— muestra el resumen de comandos./status— expone el estado del agente, proveedor, modelo y streaming, además del estado de la caché de prompts, el límite de turnos y cada servidor MCP configurado con su estado y número de herramientas./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 CPUSubir /tmp/script.sh a /home/ubuntu/bin/script.sh
El asistente reutiliza la sesión SSH activa para comandos remotos. Las transferencias abren SFTP bajo demanda y dejan rastro en los logs. Las rutas remotas relativas se resuelven respecto al directorio inicial de la sesión SFTP (normalmente el home del usuario) y los directorios que falten se crean ahí.
El agente y /connect se ejecutan en un worker en segundo plano, de modo que la TUI sigue respondiendo mientras trabajan; si envías otra petición antes de que termine la actual, se rechaza con un aviso en el panel de conversación.
Configuración adicional
-
conf/app_config.jsondefine 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.confcontrola el proveedor LLM, las herramientas y los timeouts. Copiaconf/agent.conf.exampleantes de modificarlo. OpenAI admitechat_completions(predeterminado) yresponses; los valores comunesmax_tokensy de razonamiento se normalizan para el endpoint elegido. Usa Responses para function tools de GPT-5.x con razonamiento activo. El modo opcionalstatefulpuede reutilizarprevious_response_id, peroreasoningContenttodavía no conserva toda la continuidad multi-turno.
ManténOPENAI_API_KEYen el entorno. El ejemplo usagpt-6.1-sol, Responses,reasoning_effort: mediumymax_tokens: 32768(efectivo comomax_output_tokens); la configuración real usa65536. Bedrock mantiene8192, el timeout remoto900segundos yremote_command.max_output_chars: 120000.
Para LM Studio ejecutalms server start; para Cerebras exportaCEREBRAS_API_KEY. Mistral AI usaMISTRAL_API_KEY,provider: mistral,reasoning_effort: highymax_tokens: 16184(mistral-medium-3.5) por defecto. Google Gemini usaGEMINI_API_KEY(oGOOGLE_API_KEY, oapi_key_env),provider: geminiygemini-3.8-flashcontemperature: 0.3ymax_tokens: 16384(enviado comomax_output_tokens); el resto deparamsva aGenerateContentConfigyclient_argsal cliente degoogle-genai(vertexai: truepara Vertex AI). -
Prompt caching: cada bloque de proveedor admite un objeto opcional
cache(enabled,strategy,ttl,system_prompt_ttl,tools_ttl,cache_key) que se traduce alCacheConfigde Strands. Bedrock usa por defectoenabled: trueconstrategy: "auto"(cache points solo en modelos Claude). OpenAI y Mistral usan por defectoenabled: truey envían unprompt_cache_keyestable derivado de la ruta de configuración y demodel_id; fijacache_keyo ponlo afalsepara desactivarlo. LM Studio queda desactivado salvo que lo actives; Ollama, Cerebras y Gemini ignoran el bloque con un aviso en el log (Gemini cachea prefijos de forma implícita y los tokens cacheados que informa siguen apareciendo en/status)./statusindica si la caché está activa y los tokens de entrada cacheados frente al total del último turno. -
Límite de turnos:
agent.max_turns(por defecto25) acota los turnos, cada uno una llamada al modelo más las herramientas que solicite, que el agente puede dedicar a una instrucción. Al alcanzarlo el agente se detiene de forma limpia, el panel añade un aviso sugiriendo una instrucción más acotada y se registra un WARNING;nullo0desactiva el límite y/statusmuestra el valor activo. -
Herramientas:
tools.defaultindica qué Strands Agents Tools se registran (el ejemplo activashell,file_read,file_writeysleep; si omites la clave se activan todas).remote_ssh_command,remote_sftp_transferylocal_datetimeestán siempre disponibles. Eltimeout_secondsderemote_ssh_command(900por defecto) acota el tiempo total de ejecución del comando, no la inactividad entre lecturas de salida; pide al agente que pase un valor mayor para tareas largas. -
Servidores MCP: el bloque
mcpdeclara transportesstdio,sseystreamable_http(MCP 2.x); los transportes HTTP respetanheaders. Los servidores arrancan en paralelo ytimeout_seconds(30por defecto) acota tanto el arranque de cada servidor como sus peticiones, así que un servidor colgado ya no bloquea la TUI. Un servidor que no arranca se omite con un aviso en el panel de conversación y/statuslista cada servidor con su estado y número de herramientas.
Solución de problemas
- Colores incorrectos: revisa
TERMy cambia axterm-256color. - El asistente no responde: comprueba
conf/agent.conf, credenciales ylogs/app.log. - Mensaje "No hay una conexión SSH activa": ejecuta
/connectantes de pedir acciones remotas. - Fallo SFTP tras un
/connectcorrecto: el shell remoto puede imprimir banners en sesiones no interactivas (p. ej.pyfigleten~/.bashrc). Envuelve la salida decorativa en una comprobación interactiva o usaSubsystem sftp internal-sftpen el servidor. - Credenciales en logs: las contraseñas de
/connectse enmascaran como***enlogs/app.log. - El agente se detuvo con un aviso de límite de turnos: la instrucción necesitaba más de
agent.max_turnsturnos o el modelo entró en bucle pidiendo herramientas (por ejemplo con argumentos vacíos). Divide la petición en instrucciones más pequeñas; si la tarea realmente necesita más pasos, subeagent.max_turnsenconf/agent.conf. - Un servidor MCP no arrancó: el panel de conversación muestra un aviso al iniciar y
/statuslista cada servidor MCP configurado con su estado y número de herramientas. El mensaje indica la causa (comando no encontrado, proceso terminado antes de tiempo, HTTP 401/403/404, sin conexión, sin respuesta entimeout_seconds, variables de entorno sin definir) y qué corregir enconf/agent.conf. El agente arranca igualmente sin las herramientas de ese servidor;logs/app.logconserva la traza completa.
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.