SSH

You run a Zero-Trust SSH orchestration layer that lets AI assistants securely manage servers. With declarative policy-as-code, you define who can do what, on which hosts, and what commands are allowed, while all actions are auditable. This approach keeps AI-assisted operations safe, reproducible, and compliant across your fleet.

How to use

Install and run the MCP SSH Orchestrator to enable AI-driven server management with deny-by-default access, policy enforcement, and structured audit logs. Use an MCP client (Cursor or Claude Desktop) to connect and issue high-level intents like checking system status, reviewing logs, or safely executing non-destructive tasks.

Typical usage patterns include: discovering available hosts, previewing commands before execution, running approved commands across tagged groups, and streaming real-time progress and results. All actions are filtered by your policy files and logged for later review.

How to install

# Optional one-time bootstrap via compose helper (recommended)
./compose/setup.sh enduser

# Or pull and run manually

# Pull the latest release image
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:latest

# Create directories for config, keys, and secrets
mkdir -p ~/mcp-ssh/{config,keys,secrets}

# Copy example configs to get started quickly
cp examples/example-servers.yml ~/mcp-ssh/config/servers.yml
cp examples/example-credentials.yml ~/mcp-ssh/config/credentials.yml
cp examples/example-policy.yml ~/mcp-ssh/config/policy.yml

# Add your SSH key (replace with your private key file)
cp ~/.ssh/id_ed25519 ~/mcp-ssh/keys/
chmod 0400 ~/mcp-ssh/keys/id_ed25519

# (Optional) Pin trusted hosts and prepare secret files
cp ~/.ssh/known_hosts ~/mcp-ssh/keys/known_hosts

# Option 1: Individual secret files (Docker secrets compatible)
cat > ~/mcp-ssh/secrets/prod_db_password.txt <<'EOF'
CHANGE-ME
EOF
chmod 600 ~/mcp-ssh/secrets/prod_db_password.txt

# Option 2: Consolidated .env file (recommended for easier management)
cat > ~/mcp-ssh/secrets/.env <<'EOF'
# SSH Passwords
prod_db_password=CHANGE-ME
lab_password=CHANGE-ME-TOO

# SSH Key Passphrases
prod_key_passphrase=CHANGE-ME-PASSPHRASE
EOF
chmod 600 ~/mcp-ssh/secrets/.env
# Note: .env supports KEY=value format, comments, and quoted values
# See docs/wiki/06.2-credentials.yml.md for details

Launch the orchestrator container

docker run -d --name mcp-ssh-orchestrator \
  -v ~/mcp-ssh/config:/app/config:ro \
  -v ~/mcp-ssh/keys:/app/keys:ro \
  -v ~/mcp-ssh/secrets:/app/secrets:ro \
  ghcr.io/samerfarida/mcp-ssh-orchestrator:latest

Connect your MCP client

You connect with an MCP client by configuring it to run the orchestrator container as needed. The following example shows a minimal setup for Cursor to launch the orchestrator container.

{
  "mcpServers": {
    "mcp-ssh-orchestrator": {
      "command": "docker",
      "args": ["start", "-a", "mcp-ssh-orchestrator"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}

Test the connection

echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_list_hosts","arguments":{}},"id":1}' | \
  docker run -i --rm \
    -v ~/mcp-ssh/config:/app/config:ro \
    -v ~/mcp-ssh/keys:/app/keys:ro \
    -v ~/mcp-ssh/secrets:/app/secrets:ro \
    ghcr.io/samerfarida/mcp-ssh-orchestrator:latest

Cursor/Claude should now show the orchestrator as connected. Jump to the Usage Cookbook for guided scenarios.

## Configuration & security

Policy-as-code defines what hosts exist, which credentials are available, and which commands are allowed. The three primary files are: `config/servers.yml`, `config/credentials.yml`, and `config/policy.yml`. These files drive all decision-making during SSH tool invocations and are mirrored in the audit logs for traceability.

Security layers include deny-by-default execution, IP allowlists, host key verification, non-root container execution, and resource limiting. Logs capture timestamps, hashes, and IPs to support forensic review.

## Examples & scenarios

Scenario breakdowns show safe, auditable interactions with observability and control. You can preview commands with `ssh_plan`, review results, and then execute only the approved actions on the targeted hosts.

## Troubleshooting & notes

If you encounter connectivity or policy-denial issues, review the policy files for allowed binaries and arguments, ensure secret files are readable by the orchestrator, and confirm tag-based host selection aligns with your infrastructure. Check the audit logs for detailed context on denials and task progress.

## Available tools

### ssh\_list\_hosts

List all available servers registered in the orchestrator and their metadata.

### ssh\_describe\_host

Return details for a single host, including tags and credentials presence.

### ssh\_plan

Dry-run mode to preview commands and their potential changes before executing.

### ssh\_run

Execute a single command on a specified server.

### ssh\_run\_on\_tag

Execute a command across multiple servers filtered by tag.

### ssh\_run\_async

Start a long-running task in the background and monitor progress.

### ssh\_get\_task\_status

Check the progress of an asynchronous task.

### ssh\_get\_task\_output

Stream live output from a running task.

### ssh\_get\_task\_result

Retrieve the final results of a completed task.

### ssh\_cancel

Safely stop a synchronous task in progress.

### ssh\_cancel\_async\_task

Safely stop an asynchronous task.

### ssh\_reload\_config

Reload hosts, credentials, and policies without restarting the server.

### ssh\_ping

Verify connectivity to a host from the orchestrator.