Hoop (by hoophq, MIT, ~800 stars) is a unified protocol gateway: MCP, LLM and database access all go through one policy surface. Its client is called hsh (Hoop Shell Plugins): a CLI + shell integration (ssh/kubectl plugins), paired with the privileged daemon hsh-tunneld providing local tunnels (*.hoop domains) and ephemeral kubeconfig issuance.

In one sentence: consolidate "who can touch which database/model" into one gateway; the client handles seamless access.

You want zero-trust access management: one gateway for databases, infrastructure and services, with identity-based access instead of SSH keys and VPNs — hoop is that gateway, and its CLI (hsh) is the client. The two things people trip on: the download from GitHub direct is slow on mainland networks (use the gh-proxy prefix), and features split into two layers — the CLI layer (status/config/login/kubeconfig, zero privileges, verified) vs the daemon layer (tunnels/privileged ports, needs systemd + sudo, not verified here). Know which layer you need before installing.

When to use it:

• Identity-based access to databases/infrastructure via one gateway;
• Issuing temporary kubeconfigs for k9s/helm/kubectl;
• Tunnel/privileged-port features via the daemon (full install).

When not to use it: plain single-machine workflows with no gateway — the CLI alone is mostly a client for a gateway you must run somewhere.

note: why gh-proxy first: mainland GitHub direct is slow, verified path

# Source: Trove detailed guide · verified 2026-08-28
curl -sL -o hsh.tar.gz https://gh-proxy.com/https://github.com/hoophq/hsh/releases/download/v0.3.2/hsh-linux-x64.tar.gz
tar xzf hsh.tar.gz
./hsh-linux-x64/hsh --version

Expected output: 0.3.2 (hsh-tunneld 1.86.0)

Step 1: Confirm version and extraction integrity

Why: --version shows both hsh and bundled tunneld versions — the most direct confirmation that the download is complete and extraction succeeded.

# Source: Trove detailed guide · verified 2026-08-28
./hsh-linux-x64/hsh --version

Expected output: 0.3.2 (hsh-tunneld 1.86.0)

Stuck? How to recover:

• version mismatch → re-download and check tarball integrity;
• command not found → back to step 1 and confirm the extracted directory path.

Step 2: Confirm the config and status surface

Why: after hsh config set api-url, hsh status shows the gateway address you configured and the plugin list — the CLI layer's read/write path works.

# Source: Trove detailed guide · verified 2026-08-28
hsh status

Expected output: Version 0.3.2 + API URL (configured) + Auth (not authenticated) + Plugins (ssh, kubectl)

Stuck? How to recover:

• status shows not configured → run hsh config set api-url ... first, then check;
• login needed → hsh login goes through the auth flow (needs a gateway-side account, not verified here).

The CLI layer is a Bun single-binary tarball: extract and run, no system directories, no background process. hsh config set api-url writes the gateway address into ~/.hsh/; hsh status shows connection state; hsh login authenticates; hsh kubeconfig <name> issues a temporary kubeconfig. The daemon layer (hsh-tunneld, systemd unit) is for tunnels and privileged ports.

Key concepts:

• CLI layer: non-privileged, fully uninstallable, covers daily operations;
• Daemon layer: systemd + sudo (writes /etc/hsh/, /var/run/hsh/), for tunnels;
• Plugins: status shows ssh, kubectl plugins.

Where it writes: ~/.hsh/ (CLI layer); /etc/hsh/, /var/run/hsh/, systemd (daemon layer).

Measured command = hsh CLI tarball (verified in this environment 2026-08-28, hsh 0.3.2, gh-proxy accelerated); full form = hsh CLI (Bun binary, non-privileged) + hsh-tunneld daemon (Go, needs systemd + sudo, install.sh installs to /etc/hsh/ + /var/run/hsh/, privileged install not executed in this environment); hoop repo release 1.150.1 (2026-08-27) provides hsh-tunneld + install/uninstall scripts; hsh CLI repo hoophq/hsh v0.3.2 (2026-06-03) provides all-platform tarballs

Step 1: Install the CLI layer (why CLI first: non-privileged, fully uninstallable, covers daily operations)

Why: the CLI layer is a Bun single-binary tarball — extract and run, no system directories, no background process. Mainland GitHub direct is slow, so download URLs use the gh-proxy prefix — the verified path. After install, --version shows both the hsh and bundled tunneld versions.

# Source: Trove detailed guide · verified 2026-08-28
curl -sL -o hsh.tar.gz https://gh-proxy.com/https://github.com/hoophq/hsh/releases/download/v0.3.2/hsh-linux-x64.tar.gz
tar xzf hsh.tar.gz
./hsh-linux-x64/hsh --version

Expected output: 0.3.2 (hsh-tunneld 1.86.0)

After install, confirm:

• --version prints 0.3.2 (hsh-tunneld 1.86.0);
• ./hsh-linux-x64/hsh status runs (see daily usage).

Stuck? How to recover:

• curl download timeout → confirm the network can reach gh-proxy (probe with curl -I first); retry with a proxy or mirror prefix;
• tar extraction error → check download integrity (re-download), confirm xz support on the system;
• want hsh directly on PATH → put the extracted directory on PATH, or symlink to /usr/local/bin (verified with relative-path calls, no global install done).

Step 2: Run config and status (no daemon needed)

Why: hsh config set api-url writes the gateway address into ~/.hsh/; hsh status shows the current connection state. These two commands are the first step of daily troubleshooting — first see "configured or not, authenticated or not", then decide next steps.

# Source: Trove detailed guide · verified 2026-08-28
hsh config set api-url https://your-hoop-gateway

Expected output: config written to ~/.hsh/

# Source: Trove detailed guide · verified 2026-08-28
hsh status

Expected output: Version 0.3.2 + API URL (not configured) + Auth (not authenticated) + Plugins (ssh, kubectl)

After install, confirm:

• status shows the API URL changed to the address you configured;
• the Plugins list shows ssh, kubectl.

Stuck? How to recover:

• status shows not configured → run hsh config set api-url ... first, then check;
• login needed → hsh login goes through the auth flow (needs a gateway-side account).

Step 3: Temporary kubeconfig + tunnels (as needed)

Why: hsh kubeconfig prod-db issues a temporary kubeconfig for k9s/helm/kubectl (needs auth + connection); tunnel features need the daemon.

# Source: Trove detailed guide · verified 2026-08-28
hsh kubeconfig prod-db

Expected output: temporary kubeconfig path (for k9s/helm/kubectl)

# Source: Trove detailed guide · verified 2026-08-28
hsh tunnel status

Expected output: hsh-tunneld daemon status (prompts when not installed)

After install, confirm:

• kubeconfig path printed and usable by kubectl;
• tunnel status reports daemon state.

Stuck? How to recover:

• kubeconfig errors → confirm auth and gateway connectivity first;
• tunnel not available → the daemon layer needs the full install (systemd + sudo).

Startup and entry

The CLI has no resident process; use hsh subcommands directly; tunnel/privileged features need the daemon (full install).

Common operations

Operation 1: View status (verified here)

# Source: Trove detailed guide · verified 2026-08-28
hsh status

Expected output: Version 0.3.2 + API URL (not configured) + Auth (not authenticated) + Plugins (ssh, kubectl)

Operation 2: Configure the gateway address

# Source: Trove detailed guide · verified 2026-08-28
hsh config set api-url https://your-hoop-gateway

Expected output: config written to ~/.hsh/

Operation 3: Login (needs a gateway)

# Source: Trove detailed guide · verified 2026-08-28
hsh login

Expected output: auth flow (token stored in ~/.hsh/)

Operation 4: Issue a temporary kubeconfig (needs auth + connection)

# Source: Trove detailed guide · verified 2026-08-28
hsh kubeconfig prod-db

Expected output: temporary kubeconfig path (for k9s/helm/kubectl)

Operation 5: Tunnel control (needs the daemon)

# Source: Trove detailed guide · verified 2026-08-28
hsh tunnel status

Expected output: hsh-tunneld daemon status (prompts when not installed)

Data and directories

• Config and auth: ~/.hsh/;
• Daemon: /etc/hsh/config.toml (sudo), /var/run/hsh/, systemd unit hsh-tunneld.

Same source as the tool-page matrix — 19 pairs total (2 measured compatible / 17 inferred possibly compatible / 0 inferred possibly conflicting); full pairs, states and evidence: Conflict pairs (co-install matrix).

• No standalone handbook yet; for install/uninstall issues first see the agent-executable guide notes

# Source: Trove detailed guide · verified 2026-08-28
rm -rf ~/.hsh; sudo rm -f /usr/local/bin/hsh /usr/local/bin/hsh-tunneld; sudo systemctl stop hsh-tunneld 2>/dev/null || true

note: CLI layer cleans itself (remove binary + ~/.hsh/); daemon layer uses the official uninstall.sh (privileged install not executed here, systemd unit cleanup not verified)

# Source: Trove detailed guide · verified 2026-08-28
rm -rf ~/.hsh
rm -f /usr/local/bin/hsh /usr/local/bin/hsh-tunneld
sudo systemctl stop hsh-tunneld 2>/dev/null || true
command -v hsh >/dev/null 2>&1 && echo '残留: hsh 仍存在' || echo 'hoop removed: OK'

Expected output: hoop removed: OK

Manual checklist (for full cleanup):

• /etc/hsh/config.toml (sudo cleanup);
• systemd unit and /var/run/hsh/ (daemon install residue).

• Runtime preflight (Linux x86_64; full install needs systemd + sudo)
• Official tarball (CLI layer measured here); direct GitHub from China is slow and must use gh-proxy
• Each operation = one command block + expected output
• CLI layer cleans itself; daemon layer uses the official uninstall.sh (privileged install not measured here)
• Heavy entry: full form needs systemd + sudo + TUN (privileged daemon); pure CLI form is lightweight

• Q: Is the CLI layer enough? A: daily status/config/login/kubeconfig all work; tunnel and privileged-port features need the daemon (full install).
• Q: Slow domestic downloads? A: all download URLs already carry the gh-proxy prefix; if still failing, probe connectivity to gh-proxy first.
• Q: hsh command not found? A: this guide calls it by relative path ./hsh-linux-x64/hsh; for global use add it to PATH or symlink manually.
• Q: Residue after uninstall? A: CLI layer: delete ~/.hsh/ + the binary; daemon layer residue (systemd unit / /etc/hsh/) needs sudo manual cleanup; privileged install not verified here.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.

• Version: [1.150.1, 1.150.1] (hsh-tunneld locked; hsh CLI 0.3.2 bundled).
• Environment: Linux x86_64; full install needs systemd + sudo; CLI layer has zero privilege requirements.
• Network: GitHub direct slow, must use the gh-proxy prefix (verified path).
• Write surface: ~/.hsh/ (CLI layer); /etc/hsh/, /var/run/hsh/, systemd (daemon layer).
• Co-install: no conflict-matrix pairs yet (write surface does not overlap common tools).

• Verified: local repro log (2026-08-28 CLI smoke); local repro log (install/uninstall cycle); local repro log (network precheck).
• Not tested: daemon full install (needs root + systemd) — commands from the official install.sh, marked accordingly.

Third-party tutorials are not individually verified; check against this page and official docs.

• 官方 README：How it works + Quick Start（拦截模型 / 安装 / config / login / shell 插件） [官方文档 · hoop 官方 · 2026-08-30（v0.3.2 README）]
  拦截模型——`ssh production-server` 被 hsh 截获 → 检查本地 JWT → 在 Hoop API 找连接 → 生成临时会话 token → 经 Hoop gateway 连入（SSH 显示 token 提示）；Kubernetes 更顺滑（hsh 直接把 proxy+token 注入 kubeconfig，kubectl 直接可用）。Quick Start 四步：①下载 Releases 归档（含 hsh CLI + hsh-tunneld 守护 + 安装脚本，Linux install.sh 注册 systemd / macOS hsh-tunneld install 注册 LaunchDaemon，安装器把你加进 hsh 组）②`hsh config set api-url https://<公司>.hoop.dev` ③`hsh login`（浏览器 OAuth）④shell 配置加 `eval "$(hsh shell-init)"`（fish 用 hsh shell-init --shell fish | source）
• 官方 README：SSH / Kubernetes 插件用法 [官方文档 · hoop 官方 · 2026-08-30（v0.3.2 README）]
  SSH 插件——装好 hsh 后直接 `ssh <连接名>`（旧方式要在 web UI 找连接/复制 token/手动 ssh gateway，hsh 一步到位）；Kubernetes 插件——hsh 注入 kubeconfig，kubectl 命令无缝走 Hoop gateway（含审批/审计/策略）