Skip to content

Getting Started

Get up and running with susshi in under 5 minutes.

Prerequisites

  • Linux, macOS, or WSL
  • ssh client installed (openssh-client / openssh)

Install

paru -S susshi-bin

wget https://github.com/yatoub/susshi/releases/latest/download/susshi-linux-x86_64
chmod +x susshi-linux-x86_64 && sudo mv susshi-linux-x86_64 /usr/local/bin/susshi

wget https://github.com/yatoub/susshi/releases/latest/download/susshi-linux-x86_64-static
chmod +x susshi-linux-x86_64-static && sudo mv susshi-linux-x86_64-static /usr/local/bin/susshi

wget https://github.com/yatoub/susshi/releases/latest/download/susshi-macos-apple-silicon
chmod +x susshi-macos-apple-silicon && sudo mv susshi-macos-apple-silicon /usr/local/bin/susshi

wget https://github.com/yatoub/susshi/releases/latest/download/susshi-macos-intel
chmod +x susshi-macos-intel && sudo mv susshi-macos-intel /usr/local/bin/susshi

cargo install susshi

Adds a repo so apt upgrade picks up new releases automatically: 

curl -fsSL https://yatoub.github.io/susshi/apt-pubkey.asc | sudo gpg --dearmor -o /usr/share/keyrings/susshi.gpg
echo "deb [signed-by=/usr/share/keyrings/susshi.gpg] https://yatoub.github.io/susshi/apt stable main" | sudo tee /etc/apt/sources.list.d/susshi.list
sudo apt update && sudo apt install susshi

Adds a repo so dnf upgrade picks up new releases automatically: 

sudo rpm --import https://yatoub.github.io/susshi/apt-pubkey.asc
sudo tee /etc/yum.repos.d/susshi.repo <<'REPO'
[susshi]
name=Susshi
baseurl=https://yatoub.github.io/susshi/rpm
enabled=1
gpgcheck=1
gpgkey=https://yatoub.github.io/susshi/apt-pubkey.asc
REPO
sudo dnf install susshi

Download from the releases page.

nix run github:yatoub/susshi

Or add it as a flake input to your NixOS/home-manager config: 

inputs.susshi.url = "github:yatoub/susshi";

Verify:

susshi --version

Create your first inventory

Create ~/.susshi.yml:

defaults:
  user: "your-user"
  ssh_key: "~/.ssh/id_ed25519"

groups:
  - name: "My Servers"
    servers:
      - name: "web-01"
        host: "192.168.1.10"
        mode: "direct"
      - name: "db-01"
        host: "192.168.1.20"
        mode: "direct"

Launch the TUI

susshi

You'll see your server list. Navigate with j/k, press Enter to connect, / to search.

Essential keybindings

Key Action
j / k or ↓ / ↑ Move down / up
Enter Connect or toggle group
/ Fuzzy search
Tab Switch mode (Direct / Jump / Wallix)
f Toggle favorite
F Show favorites only
T Tunnel manager
E Expand all groups
h Keyboard help overlay
q Quit

One-shot connection (no TUI)

susshi --direct your-user@192.168.1.10

Validate your config

susshi --validate

Checks YAML syntax, variable resolution, and SSH key existence without opening a connection.

Next steps

  • Configuration reference — full schema, inheritance, variables, includes
  • TUI Guide — all keybindings, search syntax, tag filters, diagnostics
  • Use Cases — jump hosts, Wallix bastions, multi-environment setups