User Guide — Shell Sentinel
Overview
Shell Sentinel is a terminal-native companion that keeps a persistent SSH/SFTP session against a remote server and lets you manage infrastructure through natural language. The assistant understands your intent, suggests safe commands and documents every action.
Requirements
- Colour-capable terminal (recommended:
xterm-256color). - Python 3.12 (see
.python-version). - Access to a server exposing SSH/SFTP.
Installation
- Create a virtual environment:
python3.12 -m venv .venv
source .venv/bin/activate
- Install dependencies:
make install
Language configuration
The app reads SMART_AI_SYS_ADMIN_LOCALE. If the variable is not defined it
falls back to the system locale (default: English).
export SMART_AI_SYS_ADMIN_LOCALE=en # English
export SMART_AI_SYS_ADMIN_LOCALE=es # Spanish
export SMART_AI_SYS_ADMIN_LOCALE=de # German
Launching the app
make run
A retro welcome screen appears and closes automatically after 5 seconds or when you press any key.
Interface layout
- Conversation panel: renders Markdown responses from the assistant.
- Input area: multi-line editor; submit with
Ctrl+Sby default. - Footer: shows the SSH status, active provider/model and thinking state.
Core commands
Commands and aliases are available in English, Spanish and German.
/connect <host> <user> <password|key_path> [port]— open the SSH session (default port 22). SFTP opens on the first file transfer./disconnect— close the active connection./help— show the command summary./status— inspect agent, provider, model and streaming status, plus the prompt-cache state, the turn limit and every configured MCP server with its state and tool count./exit— display the confirmation dialog before quitting.
Working with the assistant
Type natural-language instructions. When the message is not a slash command, the Strands agent processes it. Examples:
-
List the top CPU processes -
Upload /tmp/script.sh to /home/ubuntu/bin/script.sh
The agent reuses the active SSH session for remote commands. File transfers open SFTP on demand through the same connection and every action is recorded in the logs. Relative remote paths are resolved under the SFTP session's starting directory (normally the user's home) and missing directories are created there.
The agent and /connect run in a background worker, so the TUI stays responsive while they work; a new submission sent before the current one finishes is rejected with a notice in the conversation panel.
Configuration reference
-
conf/app_config.jsonstores styling, prompts and shortcuts using placeholders like{{ui.output_panel.title}}that resolve per locale. -
Translations live in
conf/locales/<lang>/strings.json. Add new text with_("key")in the codebase and provide entries for every supported language. -
conf/agent.confdefines the LLM provider, tools and timeouts. Copyconf/agent.conf.examplebefore changing it. OpenAI supportschat_completions(default) andresponses; sharedmax_tokensand reasoning settings are normalized to the selected endpoint. Use Responses for GPT-5.x function tools with active reasoning. Optionalstatefulmode can reuseprevious_response_id, but multi-turnreasoningContentdoes not yet retain full continuity.
KeepOPENAI_API_KEYin the environment. The example usesgpt-6.1-sol, Responses,reasoning_effort: mediumandmax_tokens: 32768(effectivemax_output_tokens); the real configuration uses65536. Bedrock remains at8192, the remote timeout at900seconds andremote_command.max_output_chars: 120000.
Runlms server startfor LM Studio; exportCEREBRAS_API_KEYfor Cerebras. Mistral AI usesMISTRAL_API_KEY,provider: mistral, defaultreasoning_effort: highandmax_tokens: 16184(mistral-medium-3.5). Google Gemini usesGEMINI_API_KEY(orGOOGLE_API_KEY, orapi_key_env),provider: geminiandgemini-3.8-flashwithtemperature: 0.3andmax_tokens: 16384(sent asmax_output_tokens); extraparamsgo toGenerateContentConfigandclient_argsto thegoogle-genaiclient (vertexai: truefor Vertex AI). -
Prompt caching: each provider block accepts an optional
cacheobject (enabled,strategy,ttl,system_prompt_ttl,tools_ttl,cache_key) mapped to Strands'CacheConfig. Bedrock defaults toenabled: truewithstrategy: "auto"(cache points only for Claude model ids). OpenAI and Mistral default toenabled: trueand send a stableprompt_cache_keyderived from the configuration path andmodel_id; pincache_keyor set it tofalseto opt out. LM Studio is disabled unless enabled explicitly; Ollama, Cerebras and Gemini ignore the block with a logged warning (Gemini caches prefixes implicitly and its reported cached tokens still appear in/status)./statusshows whether caching is active and the cached vs total input tokens of the last turn. -
Turn limit:
agent.max_turns(default25) caps the turns, each a model call plus the tools it requests, that the agent may spend on one instruction. When it is reached the agent stops cleanly, the panel appends a warning suggesting a narrower instruction and a WARNING is logged;nullor0disables the cap and/statusshows the active value. -
Tools:
tools.defaultlists which Strands Agents Tools are registered (the example enablesshell,file_read,file_writeandsleep; omitting the key enables all of them).remote_ssh_command,remote_sftp_transferandlocal_datetimeare always available. Thetimeout_secondsofremote_ssh_command(default900) caps the total runtime of the command, not the idle time between output reads; ask the agent to pass a higher value for long-running work. -
MCP servers: the
mcpblock declaresstdio,sseandstreamable_httptransports (MCP 2.x); HTTP transports honourheaders. Servers start in parallel andtimeout_seconds(default30) bounds both the startup of each server and its requests, so a hung server no longer blocks the TUI. A server that fails to start is skipped with a warning in the conversation panel and/statuslists every server with its state and tool count.
Troubleshooting
-
Colours look wrong: verify
TERMand switch toxterm-256colorif necessary. -
Assistant not responding: review
conf/agent.conf, provider credentials andlogs/app.log. -
"No active SSH connection": run
/connectbefore asking the agent to execute remote actions. -
SFTP or transfer fails after a successful
/connect: the remote shell may print banners on non-interactive sessions (for examplepyfigletin~/.bashrc). Wrap decorative output in an interactive check or ask the server admin to useSubsystem sftp internal-sftp. -
Credentials in logs:
/connectpasswords are masked as***inlogs/app.logand echoed input. -
The agent stopped with a turn-limit warning: the instruction needed more than
agent.max_turnsturns, or the model looped requesting tools (for example with empty arguments). Split the request into smaller instructions; if the task legitimately needs more steps, raiseagent.max_turnsinconf/agent.conf. -
An MCP server did not start: the conversation panel shows a warning at startup and
/statuslists every configured MCP server with its state and tool count. The message names the cause (command not found, process exited early, HTTP 401/403/404, cannot connect, no response withintimeout_seconds, environment variables not set) and what to fix inconf/agent.conf. The agent still starts without that server's tools;logs/app.logkeeps the full trace.
Additional resources
- Contributor handbook: key policies for documentation, localisation and release cadence.
- Product overview manual: architecture, stack highlights and operational responsibilities.