Stop copy-pasting terminal output into your AI. Let your LLM SSH in and look around.
ShellGuard is an MCP server that gives LLM agents controlled bash access to remote servers over SSH. Connect your AI to production, staging, or dev servers and let it run diagnostics, inspect logs, query databases, and troubleshoot -- hands-free.
ShellGuard is the open-source security layer built by the team at . It powers Fawdy's AI-powered Linux server investigation tool that delivers plain-English root cause analysis.
MCP server that gives LLM agents read-only shell access over SSH. Powers Fawdy (fawdy.com)
You can use ShellGuard standalone with any MCP-compatible AI agent, or try the full investigation experience with Fawdy.
Why ShellGuard?
AI agents are powerful, but giving them unrestricted shell access to production servers is risky. ShellGuard solves this by enforcing read-only access at the command level. Every command is parsed, validated against an allowlist, and reconstructed before execution. If an agent tries something destructive, ShellGuard blocks it and tells the agent what to do instead.
Commands are restricted to a curated set of observation and diagnostic tools. Destructive operations are blocked with actionable suggestions so the LLM can self-correct and keep investigating:
wget -r -> "Recursive downloading is not allowed"
tail -f -> "Follow mode hangs until timeout. Use tail -n 100 for recent lines."
sed -> "Stream editing can modify files -- read-only access only. Use grep for searching."
$HOME/file -> "Variable expansion will not expand. Use absolute paths."
Quick Start
Install
brew install fawdyinc/tap/shellguard
Or download the latest binary:
curl -fsSL https://raw.githubusercontent.com/fawdyinc/shellguard/main/install.sh | sh
Or with Go:
go install github.com/fawdyinc/shellguard/cmd/shellguard@latest
Configure with an MCP Client
ShellGuard starts as a stdio MCP server -- no arguments needed. Add it to your MCP client of choice:
Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server
Or paste this into your ~/.cursor/mcp.json file. You can also install per-project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more info.
ShellGuard tries authentication methods in this order, stopping at the first success:
Priority
Method
Source
On failure
1
Explicit key
identity_file parameter in connect
Fatal -- connection fails immediately
2
ssh-agent
SSH_AUTH_SOCK unix socket
Silent -- skipped
3
Default keys
~/.ssh/id_ed25519, id_ecdsa, id_rsa
Silent -- skipped
Passphrase-protected keys are silently skipped during default key discovery. If you specify a passphrase-protected key via identity_file, the connection will fail. Add the key to your agent first: ssh-add ~/.ssh/my_key.
SSH Modes
ShellGuard supports two SSH modes:
Mode
Description
native
(Default) Uses Go's built-in SSH library. Reads ~/.ssh/config for HostName, User, Port, and IdentityFile. Lightweight, no external dependencies.
system
Uses the local ssh binary. Full ~/.ssh/config support including ProxyJump, ProxyCommand, Match blocks, and all other OpenSSH features. Requires ssh to be installed.
If you connect through bastion hosts, use ProxyJump, or rely on Match blocks in your SSH config, enable system mode:
ssh:
mode: system
export SHELLGUARD_SSH_MODE=system
If mode is set to system but the ssh binary is not found, ShellGuard logs a warning and falls back to native mode.
Native mode limitations:Match directives, ProxyJump, ProxyCommand, and ForwardAgent are not supported. Use system mode if your infrastructure requires these features.
System mode notes:
Host key verification is handled entirely by OpenSSH. The host_key_checking and known_hosts_file settings only apply in native mode.
Connections are multiplexed using OpenSSH ControlMaster, so only the first connection per host pays the SSH handshake cost.
Host Key Verification
ShellGuard verifies SSH host keys using ~/.ssh/known_hosts. Three modes are available:
Mode
Behavior
accept-new
(Default) Trust-on-first-use. Unknown hosts are accepted and written to known_hosts. Key changes are rejected.
strict
Require the host key to already exist in known_hosts. Unknown hosts are rejected.
off
Disable host key verification entirely.
If a host key has changed, remove the old entry from your known_hosts file.
Configuration
Settings can be specified in a YAML config file or via environment variables. Environment variables take precedence.
SSH mode: native (built-in) or system (uses local ssh binary)
ssh.connect_timeout
SHELLGUARD_SSH_CONNECT_TIMEOUT
10s
TCP + SSH handshake timeout
ssh.retries
SHELLGUARD_SSH_RETRIES
2
Connection/execution retry attempts
ssh.retry_backoff
SHELLGUARD_SSH_RETRY_BACKOFF
250ms
Base backoff (exponential: backoff * 2^attempt)
ssh.host_key_checking
SHELLGUARD_SSH_HOST_KEY_CHECKING
accept-new
Host key verification mode (native mode only)
ssh.known_hosts_file
SHELLGUARD_SSH_KNOWN_HOSTS_FILE
~/.ssh/known_hosts
Path to known_hosts file (native mode only)
Toolkit Provisioning
Remote servers don't always have the tools you want. On connect, ShellGuard probes for rg, jq, and yq. If any are missing, the LLM can call provision to deploy them:
Tool
Version
Architectures
rg (ripgrep)
14.1.1
x86_64, aarch64
jq
1.7.1
x86_64, aarch64
yq
4.52.2
x86_64, aarch64
Binaries are downloaded from GitHub Releases with SHA-256 verification, cached locally, and deployed to ~/.shellguard/bin/ on the remote host.
ShellGuard is great on its own, but if you want automated incident investigation with plain-English root cause reports, check out Fawdy. It connects to your Linux servers via ShellGuard and investigates incidents automatically. 10-minute setup.
