hoop

What you will run into

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.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

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).

Step by step

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.

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.

hsh config set api-url https://your-hoop-gateway

Expected output: config written to ~/.hsh/

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.

hsh kubeconfig prod-db

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

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).

How to confirm it works

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.

./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.

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).

Other environments

• Non-Linux x86_64: official tarballs for darwin etc. (not verified here, same command surface); the CLI layer is non-privileged and extracts anywhere.
• Full install (daemon layer): needs systemd + sudo (writes /etc/hsh/, /var/run/hsh/); only the CLI layer was verified here; daily operations and uninstall go through the CLI layer.
• Want it globally: put the extracted directory on PATH or symlink to /usr/local/bin (verified with relative-path calls, no global install done).

Daily usage

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)

hsh status

Expected output: Version 0.3.2 + API URL (not configured) + Auth (not authenticated) + Plugins (ssh, kubectl) Operation 2: Configure the gateway address

hsh config set api-url https://your-hoop-gateway

Expected output: config written to ~/.hsh/ Operation 3: Login (needs a gateway)

hsh login

Expected output: auth flow (token stored in ~/.hsh/) Operation 4: Issue a temporary kubeconfig (needs auth + connection)

hsh kubeconfig prod-db

Expected output: temporary kubeconfig path (for k9s/helm/kubectl) Operation 5: Tunnel control (needs the daemon)

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.

Uninstall & cleanup

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)

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).

Dependency warnings

• Version: [0.3.2, 0.3.2] (hsh CLI; bundled tunneld 1.86.0). Note 1.150.1 is the platform version number, unrelated to the CLI — the earlier version line mislabeled it as the CLI version, corrected 2026-08-31.
• 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).

FAQ

• 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.