hop

hop

不必再输入冗长的 SSH 命令。只需运行 hop prod，即可连接。

为什么选择 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

安装

Homebrew（macOS/Linux）

brew install danmartuszewski/tap/hop

Go

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

从源代码安装

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

使用 AI Agent 安装

正在使用 Claude Code、Codex、Cursor 或其他编码 Agent？将下面的代码块粘贴到 Agent 中，它会为你的设备选择合适的安装方式、注册 hop 的 MCP 服务，并验证安装结果。

Install hop on this machine and register its MCP server. Do the steps in order;
stop and report on the first failure.

1. Pick ONE install method, in this priority:
   a. Homebrew (macOS or Linux):
        brew install danmartuszewski/tap/hop
   b. Go 1.26+ available:
        go install github.com/danmartuszewski/hop/cmd/hop@latest
   c. From source (no brew, no Go on PATH):
        git clone https://github.com/danmartuszewski/hop.git && cd hop && make install

2. Verify the binary is on PATH:
        hop version

3. Register the MCP server with whichever agent the user is running. Skip
   clients the user does not use:
   - Claude Code:  claude mcp add hop -- hop mcp
   - Codex CLI:    codex mcp add hop -- hop mcp
   - Claude Desktop / Cursor / Windsurf — add to the client's MCP config:
        { "hop": { "command": "hop", "args": ["mcp"] } }

4. (Optional) Seed the config from the user's existing SSH config. Preview
   first; --yes is required for a non-interactive run:
        hop import --dry-run
        hop import --yes

5. Confirm hop's MCP tools are reachable from the agent (e.g. list_connections).

Constraints:
- Do NOT run bare `hop` — it launches an interactive TUI and will hang a
  non-interactive session. Use subcommands (`hop version`, `hop list`, …).
- Do NOT modify ~/.ssh/config. hop reads it via `hop import` only.
- Do NOT commit secrets or identity files.

After step 3, restart the agent so it picks up the new MCP server.

功能

• 模糊匹配 - 输入 hop prod 即可连接到 app-server-prod-03
• TUI 仪表盘 - 使用键盘或鼠标浏览、添加、编辑和删除连接
• 导入 SSH 配置 - ~/.ssh/config 中已有服务？只需一条命令即可导入
• 导出 - 将筛选后的连接导出为 YAML，以便分享或备份
• 批量执行 - 一次在多台服务上运行命令
• 分组和标签 - 按项目、环境或自定义标签整理
• 跳板主机 - 支持用于堡垒机的 ProxyJump
• 进入指定目录 - 连接后直接进入预设的工作目录
• MCP 服务 - 让 AI 助手管理你的服务——搜索连接、运行命令、跨项目查看状态
• Mosh 支持 - 在漫游或网络不稳定时，使用 mosh 替代 SSH
• 零依赖 - 单个二进制文件，随处可用

查看所有功能的实际演示：演示录屏

Raycast 扩展

直接从 Raycast 启动连接。模糊搜索、标签和环境信息——尽在指尖。

从 Raycast Store 安装

配置

配置文件位置：~/.config/hop/config.yaml

version: 1

defaults:
  user: admin
  port: 22
  # use_mosh: true             # Uncomment to use mosh for all connections

connections:
  - id: prod-web
    host: web.example.com
    user: deploy
    identity_file: ~/.ssh/work_key   # Private key for this connection
    remote_dir: /var/www/myapp       # Land in this directory on connect
    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

  - id: remote-dev
    host: dev.example.com
    user: dan
    use_mosh: true               # Use mosh instead of SSH

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

安全提示：forward_agent: true 会将你的 SSH 密钥暴露给拥有远程服务 root 权限的任何人。仅对你完全信任的服务启用此选项。如果只是需要通过堡垒机访问内部主机，可以考虑改用 proxy_jump。

Mosh 支持

Mosh（移动 shell）适用于网络不稳定时的连接——它能妥善应对漫游、间歇性连接和高延迟。

全局默认设置——为所有连接启用 Mosh：

defaults:
  use_mosh: true

connections:
  - id: remote-dev
    host: dev.example.com

  - id: legacy-server
    host: old.example.com
    use_mosh: false              # Override: use SSH for this one

单个连接设置——为指定连接启用 Mosh：

connections:
  - id: remote-dev
    host: dev.example.com
    user: dan
    use_mosh: true

临时使用——使用 --mosh 标志，无需更改配置：

hop connect myserver --mosh
hop myserver --mosh

单个连接的 use_mosh: false 会覆盖全局默认设置。SSH 选项（端口、身份文件、代理跳转、Agent 转发）会通过 Mosh 的 --ssh 标志自动传递。Mosh 要求本地安装 mosh-client，并且远程主机上安装 mosh-server。

**注意：**无论 use_mosh 如何设置，hop exec 始终使用 SSH，因为 Mosh 专为交互式会话设计。

进入指定目录

设置 remote_dir，即可让连接直接进入特定目录，而非 $HOME：

connections:
  - id: prod-web
    host: web.example.com
    user: deploy
    remote_dir: /var/www/myapp   # cd here on connect

  - id: my-dev
    host: dev.example.com
    remote_dir: ~/projects/api   # ~ is expanded on the remote host

连接时，hop 会先运行 cd 进入指定目录，然后交给你一个正常的交互式登录 shell，因此会话的行为与常规 SSH 登录完全一致——只是所在目录不同。以下几点值得注意：

• **绝对路径和 ~ 均可使用。**远程 shell 会展开 ~ 和 ~user。
• **设计上宽容处理。**如果目录不存在或无法访问，你仍会进入 shell（位于 $HOME），而不会被踢出主机。
• 新标签页也适用。hop open 会将指定目录应用到它启动的每个终端。

**注意：**传入显式命令时（例如 hop connect web -- uptime 或 hop exec），remote_dir 会被忽略，因为这些并非交互式会话。

TUI 仪表板

使用 hop 或 hop dashboard 启动。

在仪表板中连接到服务器时（按 Enter），SSH 会话会启动，并且会话结束后，仪表板会自动返回。这样，你就可以在服务器之间快速切换，无需每次都重新启动 TUI。

如需一次性连接并退出到终端，请使用：

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

键盘快捷键

按键	操作
↑/k	上移
↓/j	下移
PgUp/PgDn	按页移动
g	跳到顶部
G	跳到底部
/	筛选连接（支持多关键词 AND 搜索）
t	按标签筛选
r	切换按最近使用排序
Enter	连接到所选项
a	添加新连接
i	从 SSH 配置导入
p	粘贴 SSH 字符串（快速添加）
e	编辑所选项
c	复制所选项（打开已预填的副本）
d	删除所选项
x	将连接导出为 YAML
y	复制 SSH 命令
T	打开主题选择器
?	显示帮助
q	退出

筛选连接

按 / 并输入关键词来筛选连接。筛选支持多关键词 AND 逻辑——用空格分隔关键词，即可查找匹配所有条件的连接。

示例：

• prod - 匹配包含“prod”的连接
• prod web - 匹配同时包含“production”和“web”的连接
• kaf staging - 匹配同时包含“kafka”和“staging”的连接

筛选会搜索连接 ID、主机、项目、环境和标签。

粘贴快速添加

按 p 并粘贴以下任意格式：

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

连接表单会打开，并预填各字段。

复制连接

在任意连接上按 c 即可创建副本。添加表单会打开，并预填原连接的所有字段——包括表单中未显示的选项，例如代理跳转和 mosh——同时提供一个不会冲突的 ID 建议（例如 web-prod → web-prod-copy）。按需调整并保存。如果选择的 ID 已存在，表单会保持打开，且保留你的编辑内容，方便你进行修改。

从 SSH 配置导入

从 ~/.ssh/config 文件导入现有连接：

从仪表板导入： 按 i 打开导入弹窗，选择要导入的连接，然后按 Enter。

从 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

导入内容：

• 主机别名会成为连接 ID
• HostName、User、Port、IdentityFile
• 跳板主机连接的 ProxyJump
• ForwardAgent 设置

跳过的内容：

• 通配符模式（Host *、Host *.example.com）
• 没有 HostName 的条目（使用别名作为主机名）

冲突处理： 如果连接 ID 已存在，导入的连接会重命名，并添加 -imported 后缀（例如，myserver → myserver-imported）。

导出连接

将部分连接导出到 YAML 文件，以便共享、备份或转移到另一台机器。

从仪表板导出： 按 x 打开导出弹窗。仅显示当前筛选后的连接——先应用文本或标签筛选以缩小选择范围。按 Space 切换项目，然后按 Enter 保存。

从 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

必须至少指定一个筛选标志或 --all。筛选条件之间使用 AND 逻辑。

主题

仪表盘内置了 16 种配色预设——每种热门主题都有深色和浅色两个版本，并分别列出，因此无论终端背景是什么，都可以选择喜欢的版本。按 T 浏览并实时预览：按 ↑/↓ 导航，按 Enter 将选择保存到配置中，按 Esc 恢复原状。

系列	深色	浅色
内置 hop	default-dark	default-light
Everforest	everforest-dark	everforest-light
Gruvbox	gruvbox-dark	gruvbox-light
Catppuccin	catppuccin-mocha	catppuccin-latte
Tokyo Night	tokyo-night-storm	tokyo-night-day
Solarized	solarized-dark	solarized-light
Nord	nord	nord-light
Dracula	dracula	alucard

选择预设后，会在配置中写入一行：

theme_preset: everforest-dark

如果未设置 theme_preset，hop 会根据终端背景自动选择 default-dark 或 default-light。

自定义覆盖

在任意预设上叠加自己的颜色：

theme_preset: everforest-dark   # optional; omit to auto-pick default
theme:                          # applies to every preset
  primary: "#0066cc"
theme_dark:                     # only applies when the preset is a dark variant
  selection: "#1f1f28"
theme_light:                    # only applies when the preset is a light variant
  foreground: "#1c1f24"

颜色值可以是带引号的 ANSI 256 色代码（"39"），也可以是十六进制字符串（"#bd93f9"）。ANSI 代码会适配终端调色板；十六进制值则是固定值。

可用的键：primary、secondary、accent、success、warning、error、muted、selection、foreground。未设置的键会依次回退到预设值和内置默认值。

CLI 命令

hop                          # Open TUI dashboard
hop <query>                  # Fuzzy match and connect
hop connect <id>             # Connect by exact ID
hop get <id> <field>         # Print single field value to stdout
hop get <id> f1,f2,f3        # Print multiple fields tab-separated
hop get <id>                 # Print all fields as "key value" lines
hop get --help               # Full field list and flags
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

目标定位

exec 和 open 等命令接受一个 目标，用于解析出一个或多个连接。目标按以下顺序匹配：

1. 命名组 — 在配置的 groups: 下定义的连接 ID 显式列表
2. 项目环境模式 — 根据 project 和 env 字段匹配连接（例如，myapp-prod 会匹配所有 project: myapp 且 env: prod 的连接）
3. Glob 模式 — 按连接 ID 通配符匹配（例如，web*、*-prod-*）
4. 模糊匹配 — 回退到对单个连接 ID 进行模糊匹配

你也可以使用 --tag 按标签筛选任意目标。

运行任何操作前，可以使用 hop resolve 预览目标会匹配哪些连接：

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

示例

# 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

使用 hop 编写脚本

hop get 会将连接字段输出到标准输出，方便直接用于 shell 管道和命令替换——可以把它看作适用于 hop 配置的 ssh -G。

# Build an ssh invocation from config:
ssh -i "$(hop get prod identity_file)" "$(hop get prod user)@$(hop get prod host)"

# Read multiple fields at once (tab-separated):
IFS=$'\t' read -r host port user < <(hop get prod host,port,user)

# Fallback when a field is empty:
hop get prod port --default 22

# Strict shells: suppress the trailing newline.
hop get prod host -n

# Dump all non-empty scalar fields (ssh -G style "key value" lines):
hop get prod

# Read a single SSH option by key:
hop get prod options.StrictHostKeyChecking

# Structured output for jq and friends:
hop get prod host,port --json | jq -r .host

仅精确匹配 ID（不进行模糊匹配），在脚本中更安全。未知 ID 会以状态码 1 退出，并提示“你是不是想找……”。完整字段列表请参阅 hop get --help。

MCP 服务（AI 助手集成）

hop 内置了 Model Context Protocol 服务，可让 Claude Code 和 Codex 等 AI 助手直接管理你的服务。你可以让助手检查生产环境中的磁盘空间、重启预发布环境中的服务，或查找属于某个项目的服务——它会发现你的连接、解析目标，并通过 hop 执行命令。

设置

Claude Code：

claude mcp add hop -- hop mcp

Codex CLI：

codex mcp add hop -- hop mcp

Claude Desktop — 将以下内容添加到配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

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

Codex — 将以下内容添加到 ~/.codex/config.toml：

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

或者自动生成 Claude Desktop 配置：

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

工具

默认情况下，仅开放只读工具：

工具	描述
list_connections	列出连接，可按项目／环境／标签筛选
search_connections	在所有连接中进行模糊搜索
get_connection	获取特定连接的详细信息
resolve_target	预览目标模式的解析结果
list_groups	列出所有命名分组
get_history	连接使用历史记录
build_ssh_command	构建完整的 SSH 命令字符串

若要启用远程命令执行，请使用 --allow-exec 启动：

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

这会添加 exec_command 工具，用于在匹配的服务上运行 shell 命令，并限制输出大小（每台主机的 stdout 和 stderr 各为 64 KiB，最多 50 台主机）。捕获过程中会限制输出大小；超出的输出将被丢弃，并在响应中标记为已截断。

资源

该服务还提供可浏览的资源：

URI	描述
hop://config	配置摘要（数量、项目、环境）
hop://connections	所有连接
hop://connections/{id}	单个连接的详细信息
hop://groups	所有分组及其成员

安全性

• MCP 不会暴露身份文件（SSH 密钥路径）
• 默认禁用远程执行，且必须显式指定 --allow-exec
• 所有日志都写入 stderr，以保持 JSON-RPC 传输内容干净

Shell 补全

# 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

标志

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

构建

make build          # Build binary to ./bin/hop
make test           # Run tests
make test-race      # Run tests with race detection (also used in CI)
make vuln           # Scan for reachable Go vulnerabilities
make test-docker    # Run tests in Docker (isolated)
make install        # Install to $GOPATH/bin
make docker         # Build Docker image

维护

通过 Dependabot 配置依赖维护，涵盖 Go 模块（包括固定版本的漏洞扫描器）、GitHub Actions 和 Docker 镜像。它每周检查一次，并创建拉取请求以供审查。Go 的次要版本和补丁更新会合并处理；主要版本更新则保持独立。

Security 工作流会在拉取请求、推送到 main 时以及每周定时运行 make vuln。也可以在 GitHub Actions 中手动启动。可利用的漏洞会导致检查失败。请在本地使用已修补且受支持的 Go 工具链运行扫描，以确保扫描结果也能反映标准库当前的修复情况。

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 .

项目结构

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

许可证

MIT 许可证 — 详情请参阅 LICENSE。