hop

hop

Stop typing long SSH commands. Just hop prod and you're in.

Why hop?

# Before: remembering and typing this every time
ssh -i ~/.ssh/work_key [email protected] -p 2222

# After
hop prod

hop prod                         # fuzzy match any server
hop exec production "uptime"     # run command on all prod servers
hop import                       # import your existing ~/.ssh/config
hop                              # launch the TUI, manage everything

Install

Homebrew (macOS/Linux)

brew install danmartuszewski/tap/hop

Go

go install github.com/danmartuszewski/hop/cmd/hop@latest

From source

git clone https://github.com/danmartuszewski/hop.git && cd hop && make build
./bin/hop

Features

• Fuzzy matching - Type hop prod to connect to app-server-prod-03
• TUI dashboard - Browse, add, edit, delete connections with keyboard or mouse
• SSH config import - Already have servers in ~/.ssh/config? Import them in one command
• Export - Export filtered connections to YAML for sharing or backup
• Multi-exec - Run commands across multiple servers at once
• Groups & tags - Organize by project, environment, or custom tags
• Jump hosts - ProxyJump support for bastion servers
• MCP server - Let AI assistants manage your servers — search connections, run commands, check status across projects
• Zero dependencies - Single binary, works anywhere

See all features in action: Demo recordings

Coming Soon: Raycast Extension

Launch connections directly from Raycast. Fuzzy search, tags, environments - all at your fingertips.

Configuration

Config file location: ~/.config/hop/config.yaml

version: 1

defaults:
  user: admin
  port: 22

connections:
  - id: prod-web
    host: web.example.com
    user: deploy
    project: myapp
    env: production
    tags: [web, prod]

  - id: prod-db
    host: db.example.com
    user: dbadmin
    port: 5432
    project: myapp
    env: production
    tags: [database, prod]

  - id: staging
    host: staging.example.com
    user: deploy
    project: myapp
    env: staging

  - id: private-server
    host: 10.0.1.50
    user: admin
    proxy_jump: bastion          # Connect via jump host
    forward_agent: true          # Forward SSH agent

groups:
  production: [prod-web, prod-db]
  web-servers: [prod-web, staging]

Security note: forward_agent: true exposes your SSH keys to anyone with root access on the remote server. Only enable this for servers you fully trust. Consider using proxy_jump instead when you just need to reach internal hosts through a bastion.

TUI Dashboard

Launch with hop or hop dashboard.

When you connect to a server from the dashboard (by pressing Enter), the SSH session starts, and the dashboard automatically returns after the session ends. This lets you quickly hop between servers without restarting the TUI each time.

For one-shot connections that exit to your terminal, use:

hop <query>           # fuzzy match and connect
hop connect <id>      # connect by exact ID

Keyboard Shortcuts

Filtering Connections

Press / to filter connections by typing keywords. The filter supports multi-keyword AND logic - separate keywords with spaces to find connections matching all terms.

Examples:

• prod - matches connections containing "prod"
• prod web - matches connections containing both "production" AND "web"
• kaf staging - matches connections with both "kafka" AND "staging"

The filter searches across connection IDs, hosts, projects, environments, and tags.

Quick Add with Paste

Press p and paste any of these formats:

[email protected]
[email protected]:2222
ssh [email protected] -p 2222
ssh://user@host:port

The connection form opens with fields pre-filled.

Importing from SSH Config

Import existing connections from your ~/.ssh/config file:

From the dashboard: Press i to open the import modal, select which connections to import, and press Enter.

From the CLI:

hop import                   # Import from ~/.ssh/config
hop import --dry-run         # Preview what would be imported
hop import --file ~/.ssh/config.d/work  # Import from custom path

What gets imported:

• Host alias becomes the connection ID
• HostName, User, Port, IdentityFile
• ProxyJump for jump host connections
• ForwardAgent setting

What gets skipped:

• Wildcard patterns (Host *, Host *.example.com)
• Entries without a HostName (alias is used as hostname)

Conflict handling: If a connection ID already exists, the imported connection is renamed with -imported suffix (e.g., myserver → myserver-imported).

Exporting Connections

Export a subset of connections to a YAML file for sharing, backup, or transferring to another machine.

From the dashboard: Press x to open the export modal. Only currently filtered connections are shown — apply text or tag filters first to narrow the selection. Toggle items with Space, then press Enter to save.

From the CLI:

hop export --all                          # Export all to stdout
hop export --all -o backup.yaml           # Export all to a file
hop export --project myapp -o myapp.yaml  # Export by project
hop export --tag database                 # Export by tag
hop export --env production               # Export by environment
hop export --id web-1,web-2              # Export specific connections

At least one filter flag or --all is required. Filters combine with AND logic.

CLI Commands

hop                          # Open TUI dashboard
hop <query>                  # Fuzzy match and connect
hop connect <id>             # Connect by exact ID
hop list                     # List all connections
hop list --json              # List as JSON
hop list --flat              # Flat list without grouping
hop import                   # Import from ~/.ssh/config
hop import --file <path>     # Import from custom path
hop import --dry-run         # Preview without importing
hop export --all             # Export all connections to stdout
hop export --project <name>  # Export filtered connections
hop export --tag <tag> -o f  # Export to file
hop open <target...>         # Open multiple terminal tabs
hop exec <target> "cmd"      # Execute command on multiple servers
hop resolve <target>         # Test which connections a target matches
hop mcp                      # Start MCP server (read-only)
hop mcp --allow-exec         # Start MCP server with remote exec
hop version                  # Show version

Targeting

Commands like exec and open accept a target that resolves to one or more connections. The target is matched in this order:

1. Named group — an explicit list of connection IDs defined under groups: in config
2. Project-env pattern — matches connections by project and env fields (e.g. myapp-prod matches all connections with project: myapp and env: prod)
3. Glob pattern — wildcard matching on connection IDs (e.g. web*, *-prod-*)
4. Fuzzy match — falls back to fuzzy matching a single connection ID

You can also filter any target by tag with --tag.

Use hop resolve to preview which connections a target will match before running anything:

hop resolve production              # see what "production" resolves to
hop resolve "web*"                  # test a glob pattern
hop resolve myapp-prod --tag=web    # combine target + tag filter

Examples

# Fuzzy connect
hop prod                # matches "prod-web", "prod-db", etc.
hop web                 # matches first *web* server

# Multi-exec with different target types
hop exec production "uptime"           # named group
hop exec myapp-prod "df -h"            # project-env pattern
hop exec "web*" "systemctl status"     # glob pattern
hop exec --tag=database "psql -c '\\l'" # tag filter

# Open multiple tabs
hop open production                    # named group
hop open web1 db1 api1                 # specific IDs
hop open myapp-prod -- "htop"          # with initial command

# List connections
hop list --flat

MCP Server (AI Assistant Integration)

hop includes a built-in Model Context Protocol server that lets AI assistants like Claude Code and Codex manage your servers directly. Ask your assistant to check disk space across production, restart a service on staging, or find which servers belong to a project — it discovers your connections, resolves targets, and executes commands through hop.

Setup

Claude Code:

claude mcp add hop -- hop mcp

Codex CLI:

codex mcp add hop -- hop mcp

Claude Desktop — add to your config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hop": {
      "command": "hop",
      "args": ["mcp"]
    }
  }
}

Codex — add to ~/.codex/config.toml:

[mcp_servers.hop]
command = "hop"
args = ["mcp"]

Or generate the Claude Desktop config automatically:

hop mcp --print-client-config                  # read-only
hop mcp --print-client-config --allow-exec     # with remote exec enabled

Tools

By default, only read-only tools are exposed:

To enable remote command execution, start with --allow-exec:

claude mcp add hop -- hop mcp --allow-exec
codex mcp add hop -- hop mcp --allow-exec

This adds the exec_command tool, which runs shell commands on matched servers with output limits (64KB/host, 50 hosts max).

Resources

The server also exposes browsable resources:

Security

• Identity files (SSH key paths) are never exposed through MCP
• Remote execution is disabled by default and requires explicit --allow-exec
• All logging goes to stderr to keep the JSON-RPC transport clean

Shell Completions

# Bash (Linux)
hop completion bash | sudo tee /etc/bash_completion.d/hop > /dev/null

# Bash (macOS with Homebrew)
hop completion bash > $(brew --prefix)/etc/bash_completion.d/hop

# Zsh (add to ~/.zshrc)
source <(hop completion zsh)

# Fish
hop completion fish > ~/.config/fish/completions/hop.fish

Flags

-c, --config <path>    # Use custom config file
-v, --verbose          # Verbose output
-q, --quiet            # Suppress non-essential output
    --dry-run          # Print SSH command without executing

Building

make build          # Build binary to ./bin/hop
make test           # Run tests
make test-docker    # Run tests in Docker (isolated)
make install        # Install to $GOPATH/bin
make docker         # Build Docker image

Docker

# Build image
docker build -t hop .

# Run interactively
docker run -it --rm hop

# Run tests in container
docker build --target tester -t hop-test .

Project Structure

hop/
├── cmd/hop/           # Main entry point
├── internal/
│   ├── cmd/           # CLI commands (cobra)
│   ├── config/        # Configuration loading/saving
│   ├── export/        # Export logic
│   ├── fuzzy/         # Fuzzy matching
│   ├── mcp/           # MCP server (tools, resources, types)
│   ├── picker/        # Connection picker (promptui)
│   ├── resolve/       # Target resolution logic
│   ├── ssh/           # SSH connection handling
│   ├── sshconfig/     # SSH config parsing
│   └── tui/           # TUI dashboard (bubbletea)
├── Dockerfile
├── Makefile
└── README.md

License

MIT License - see LICENSE for details.