AI-native SSH management — let your AI assistant manage servers for you.
Codex SSH is an AI-native SSH management tool built for AI assistants like Codex, Claude, and Hermes. It provides a structured, auditable, and secure interface between AI agents and your remote servers — turning natural language into reliable infrastructure operations.
Traditional SSH tools serve humans. Codex SSH serves AI agents — with an inventory system, jump host chaining, keychain-backed secrets, structured audit logging, and a native MCP (Model Context Protocol) server that any AI tool can consume.
One binary. Zero dependencies. AI-first.
- 🤖 AI-Native Design — Purpose-built for Codex, Claude, and Hermes with MCP server support
- 🔐 Security First — macOS Keychain secrets, Askpass injection, structured audit logs with redaction
- 🚀 Single Go Binary — Cross-platform, zero dependencies, ships anywhere
- 🔌 MCP Protocol — Standard AI tool interface (
ssh_exec,ssh_diagnose,ssh_hosts_list,ssh_audit) - 🌐 Jump Host Tunneling — Automatic multi-hop ProxyJump chain resolution
- ⚡ Parallel Execution — Run commands across multiple servers simultaneously with
@tagsyntax - 🔍 Diagnostics — One-command health checks: tmux, nohup, docker, sudo detection
- 🔧 Shell Completions — Bash, Zsh, and Fish with dynamic host/tag awareness
- 📦 SFTP File Transfer — Upload, download, and sync files with
put,get,synccommands - 🔑 Privilege Escalation — Run commands with
sudoorsuviaexec --sudo/--su - 🔄 Dynamic Host Management — Hot reload inventory and network discovery with
hosts reload/discover - 📝 Playbook Engine — Define multi-step deployment workflows in YAML (beta)
- 🏥 Health Check System — Monitor CPU, memory, disk, and load across all servers
- 🔑 SSH Key Management — List, check, and manage keys across files, SSH agent, and OS keychain
- 📊 Audit Statistics — Query audit logs with time range, export to JSON/CSV, log rotation
Homebrew (macOS / Linux):
brew install xlyoung/tap/codex-sshPre-built binary (Linux / macOS):
curl -fsSL https://raw.githubusercontent.com/xlyoung/codex-ssh/main/install.sh | bashgo install (requires Go 1.22+):
go install github.com/xlyoung/codex-ssh/cmd/codex-ssh@latest# Import your existing SSH config
codex-ssh hosts import-ssh-config
# Or add a server manually
codex-ssh hosts set myserver --host 192.168.1.100 --user deploycodex-ssh hosts list # List all managed servers
codex-ssh hosts test myserver # Test connectivity
codex-ssh doctor # Run local health checks# Single server
codex-ssh exec myserver -- "uname -a"
# All servers tagged 'web'
codex-ssh exec @web -- "systemctl status nginx"
# All servers in inventory
codex-ssh exec @all -- "df -h"codex-ssh shell myserver --cwd /srv/app# Forward local:8080 to remote 127.0.0.1:80
codex-ssh tunnel myserver --local 8080 --target 127.0.0.1:80
# Start a SOCKS5 proxy
codex-ssh proxy myserver --local 1080 --backgroundcodex-ssh diagnose myservercodex-ssh audit query --host myserver --format text┌─────────────────────────────────────────────────────┐
│ AI Agent Layer │
│ Codex · Claude · Hermes · Cursor │
└──────────────────────────┬──────────────────────────┘
│ MCP (stdio)
┌──────────────────────────▼──────────────────────────┐
│ MCP Server Layer │
│ ssh_exec · ssh_hosts_list · ssh_diagnose · │
│ ssh_audit │
└──────────────────────────┬──────────────────────────┘
│
┌──────────────────────────▼──────────────────────────┐
│ CLI / Command Layer │
│ exec · shell · tunnel · proxy · job · audit · │
│ diagnose · hosts · secret · completion │
└──────────────────────────┬──────────────────────────┘
│
┌──────────────────────────▼──────────────────────────┐
│ Core Engine Layer │
│ executor · hosts · secrets · config │
│ tunnel · proxy · jobs · audit │
└──────────────────────────┬──────────────────────────┘
│
┌──────────────────────────▼──────────────────────────┐
│ Transport Layer │
│ OpenSSH · SSH Agent · Keychain · Askpass │
└──────────────────────────┬──────────────────────────┘
│
┌──────────────────────────▼──────────────────────────┐
│ Target Layer │
│ Direct · Jump Hosts · ProxyJump Chains │
└─────────────────────────────────────────────────────┘
Codex SSH includes a built-in MCP (Model Context Protocol) server that exposes SSH operations as standard AI tools.
codex-ssh mcp serve| Tool | Description |
|---|---|
ssh_hosts_list |
List all hosts in the inventory |
ssh_exec |
Execute a command on a remote host (with timeout support) |
ssh_diagnose |
Diagnose connectivity and remote capabilities |
ssh_audit |
Query audit logs for SSH operations |
Add to your Claude Desktop claude_desktop_config.json:
{
"mcpServers": {
"codex-ssh": {
"command": "codex-ssh",
"args": ["mcp", "serve"]
}
}
}Add to your MCP settings:
{
"mcpServers": {
"codex-ssh": {
"command": "codex-ssh",
"args": ["mcp", "serve"]
}
}
}Once connected, your AI assistant can list servers, execute commands, run diagnostics, and query audit logs — all through structured tool calls.
| Document | Description |
|---|---|
| Requirements | Feature specifications and design details |
| Roadmap | Full feature roadmap (P0 → P2) |
| Contributing Guide | How to contribute to the project |
| Code of Conduct | Community guidelines |
codex-ssh/
├── cmd/codex-ssh/ # Main entry point
├── internal/ # Internal packages
│ ├── cli/ # CLI commands & shell completions
│ ├── config/ # Configuration management
│ ├── hosts/ # Host inventory
│ ├── secrets/ # Keychain password management
│ ├── sshargs/ # SSH argument builder
│ ├── sshconfig/ # ~/.ssh/config parser
│ ├── executor/ # Remote command execution
│ ├── tunnel/ # Port forwarding
│ ├── proxy/ # SOCKS5 proxy
│ ├── jobs/ # Background job management
│ ├── audit/ # Structured audit logging
│ ├── askpass/ # Password injection
│ ├── mcp/ # MCP server (JSON-RPC)
│ ├── runtime/ # Runtime state
│ └── validate/ # Input validation
├── pkg/model/ # Shared data models
├── scripts/ # Build & install scripts
├── defaults/ # Default config templates
└── docs/ # Documentation
We welcome contributions! Please read the Contributing Guide for details.
# Fork and clone
git clone https://github.com/<your-username>/codex-ssh.git
cd codex-ssh
# Build
go build ./cmd/codex-ssh
# Test
go test -race ./...
# Lint
golangci-lint runWe follow Conventional Commits:
feat:, fix:, docs:, test:, refactor:, perf:, ci:, chore:
MIT License — Copyright (c) zhuohua yang
Codex SSH · Built with ❤️ by zhuohua yang