Shellguard

What is Shellguard?

Shellguard is an MCP server that gives LLM agents read-only bash access to remote servers over SSH. It allows AI assistants to run diagnostics, inspect logs, query databases, and troubleshoot remote servers without manual context-switching. Commands are restricted to a curated set of read-only tools; destructive operations are blocked with actionable suggestions.

How to use Shellguard?

Install via Homebrew (brew install jonchun/tap/shellguard), curl, or Go install. Then add it as a stdio MCP server to your client (Cursor, Claude Desktop, Claude Code, OpenCode, VS Code, Zed, Roo Code) using the command shellguard with no arguments. Configuration for SSH can be set in a YAML file (~/.config/shellguard/config.yaml) or via environment variables.

Key features of Shellguard

• Exposes seven read-only tools: connect, execute, list_commands, disconnect, provision, download_file, sleep
• Parses shell commands into AST and rejects unsafe syntax
• Validates commands against an allowlist with explicit denylist
• Supports native (built-in) and system (local ssh binary) SSH modes
• Verifies host keys with accept-new, strict, or off modes
• Probes and provisions diagnostic tools (rg, jq, yq) on remote hosts

Use cases of Shellguard

• Investigate production incidents by running diagnostics on remote servers
• Query databases or inspect logs without leaving the AI chat interface
• Troubleshoot server behaviour by executing read-only commands
• Deploy common diagnostic tools to servers that lack them

FAQ from Shellguard

What commands can the LLM run?

Only read-only commands from a curated allowlist. Every command is parsed, validated against the allowlist, reconstructed to prevent injection, and then executed with per-command timeouts and output truncation.

How does Shellguard prevent destructive actions?

Commands are parsed into an AST; shell tricks like semicolons, redirections, and command substitution are rejected at the syntax level. Destructive operations (e.g., wget -r, tail -f, sed) are blocked with specific suggestions so the LLM can self-correct.

What SSH authentication methods are supported?

Shellguard tries in order: explicit key (identity_file parameter in connect), ssh-agent, then default keys (~/.ssh/id_ed25519, id_ecdsa, id_rsa). Passphrase-protected keys are silently skipped unless specified via identity_file, which will cause a fatal error.

Can I use bastion hosts or ProxyJump?

Yes. Shellguard offers a "system" SSH mode that uses the local ssh binary, providing full support for ProxyJump, ProxyCommand, and Match blocks. Native mode (default) does not support these features, so switch to system mode if your infrastructure requires them.

What are the size and timeout limits?

The download_file tool has a 50MB limit. The sleep tool can wait up to 15 seconds between diagnostic checks. Per-command timeouts and output truncation are applied automatically.