Aegis-SSH-MCP

A thin MCP-native SSH bridge for AI agents.

Aegis lets AI agents run approved commands on Linux hosts over SSH without giving them unrestricted shell access.

Aegis exposes host-scoped MCP tools backed by SSH, with rule-based validation, ephemeral per-request execution, and audit logging. It is designed to work with existing Linux permissions, sudo policy, and host security rather than replace them.

Quick links:

• Quick start
• How it works
• Configuration
• Connect a client
• Security model
• Docs
• Support

Quick start

The checked-in docker-compose.yml is the recommended deployment path. It runs Aegis over SSE on http://localhost:8443 by default and ships with starter rule profiles in rules/.

1. Create or populate these folders next to docker-compose.yml:

./configs
./rules
./keys
./certs   # only if you want HTTPS

2. Put an SSH private key in keys/ and keep its permissions strict.

3. Add a host config in configs/docker.json:

{
  "alias": "docker",
  "host_ip": "192.168.1.10",
  "ssh_port": 22,
  "ssh_user": "ops",
  "auth_method": "key",
  "key_path": "/keys/docker_ed25519",
  "rule_profile": "docker-readonly",
  "timeout_seconds": 30,
  "host_key_fingerprint": "SHA256:replace-this-with-your-real-host-key",
  "api_keys": [
    "change-me-docker-key"
  ]
}

4. Start the service:

docker compose pull
docker compose up -d
docker compose logs -f aegis-ssh-mcp

5. Connect your MCP client to:

http://localhost:8443/mcp/docker/sse
Authorization: Bearer change-me-docker-key

If you want HTTPS, uncomment the TLS lines in docker-compose.yml and set AEGIS_SSE_BASE_URL to your real external address.

git clone https://github.com/sparksbenjamin/Aegis-SSH-MCP.git
cd Aegis-SSH-MCP
go build -o aegis-ssh-mcp .

Why it exists

Most AI infrastructure tooling tends toward one of two extremes:

• raw shell access with very little control
• a heavy replacement platform for existing SSH and Linux workflows

Aegis is the middle path:

Keep SSH authoritative. Keep Linux authoritative. Keep infrastructure ownership where it already belongs.

It gives MCP clients a controlled way to reach real hosts without turning Aegis into a replacement for your existing security model.

What it does

• Creates one host-scoped MCP endpoint per host config
• Exposes one host-scoped SSH tool plus aegis_status for that endpoint
• Validates commands against rule profiles before SSH is attempted
• Opens a fresh SSH session for every request
• Supports both sse and stdio transport
• Logs command attempts for audit visibility
• Supports host key pinning, bearer tokens, and optional output redaction
• Hot-reloads config and rule changes from disk

What it does not do

• Replace SSH, Linux permissions, or sudo policy
• Provide OS-level sandboxing or full IAM-style RBAC
• Keep persistent remote shells, PTYs, or hidden session state
• Support SSH agent forwarding or ~/.ssh/config
• Pause commands for human approval
• Act as a full autonomous infrastructure platform

How it works

For each allowed request, Aegis parses the command, validates it against the assigned rule profile, opens a new non-interactive SSH session, runs the command, returns the output, and disconnects immediately.

+-------------------+
| MCP Client / LLM  |
| Claude / OpenAI   |
| LibreChat / SSE   |
+---------+---------+
          |
          | MCP (HTTP/SSE or stdio)
          |
+---------v---------+
|  Aegis-SSH-MCP    |
|-------------------|
| Bearer Auth       |
| Rule Validation   |
| Audit Logging     |
| Host Isolation    |
| Ephemeral SSH     |
+---------+---------+
          |
          | Standard SSH
          |
+---------v---------+
| Remote Linux Host |
|-------------------|
| SSH Permissions   |
| sudo Policies     |
| auditd/journald   |
| Host Security     |
+-------------------+

Configuration

Host configs

One JSON file in configs/ equals one remote host.

• One host config = one MCP endpoint
• One host config = one host-scoped SSH tool
• One host config = one assigned rule profile
• One host config = one bearer-token boundary for SSE

Use simple aliases such as web-01 or docker. The alias becomes part of the endpoint path and tool name.

Rule profiles

Each host config points to one rule profile with:

"rule_profile": "docker-readonly"

Rule profiles live in rules/ and decide which command shapes are allowed or blocked before SSH is attempted.

Connect a client

Each host config becomes its own host-scoped SSE endpoint:

http://YOUR_AEGIS_HOST:8443/mcp/<alias>/sse

Clients must send the configured bearer token:

Authorization: Bearer YOUR_TOKEN

Quick reachability check:

curl -i -N \
  -H "Authorization: Bearer change-me-docker-key" \
  http://YOUR_AEGIS_HOST:8443/mcp/docker/sse

If the token is valid, Aegis should return 200 OK and keep the SSE stream open.

If one agent needs access to two different hosts, add Aegis twice in the client with one endpoint URL and one bearer token per host alias.

mcpSettings:
  allowedDomains:
    - "192.168.100.184"

mcpServers:
  aegis-docker:
    type: sse
    url: "http://192.168.100.184:8443/mcp/docker/sse"
    headers:
      Authorization: "Bearer change-me-docker-key"
    timeout: 120000
    initTimeout: 30000

Security model

Aegis is a controlled SSH execution bridge, not a full security platform.

Security boundaries come from the combination of:

• SSH authentication
• Linux user permissions
• sudo configuration
• host isolation
• command validation rules
• bearer-authenticated MCP access
• audit logging
• ephemeral execution isolation

Operators still own:

• credential management
• host hardening
• least-privilege remote accounts
• network security
• audit retention
• infrastructure segmentation

Docs

The README stays focused on deployment and first-use. The deeper docs below are still in the repo, but their core purpose is summarized here first.

Authoring rule for this README: docs/readme-authoring.md

Screenshots

Status

Aegis is early-stage but operational.

Support

For bugs, setup questions, or operational feedback, open an issue in this repository.

Primary maintainer: @sparksbenjamin

Contributions are welcome, especially around:

• MCP client interoperability
• rule validation improvements
• observability
• deployment hardening
• transport support
• testing and validation

Until a dedicated contributing guide lands, opening an issue before a large change is the best way to align on direction.

License

MIT License