18 KiB

Raw Permalink Blame History

shellm Quickstart — From Tarball to a Live SSH Session in Under Five Minutes

A getting-started guide for shellm 1.1.0, the Rust/iced port of secpanel. Covers install, first run, profile creation, the first SSH connect, keypair generation, and the new dual-pane SCP browser. Written for Linux desktops running X11 or Wayland, with notes for macOS users. Updated for the 1.1.0 release in 2026.

The fastest path through shellm is straightforward: install the build dependencies, compile the binary, run it once to let it scaffold ~/.shellm/, create a profile pointing at an SSH host you already have credentials for, click Connect, and verify that the SSH session opens in your terminal. From there the rest of the application — the SCP browser, keypair generation, port forwards, key distribution, GPG data protection — is discoverable in the same four-tab-plus-one layout that secpanel users have known for two decades. This document walks that path step by step, with the actual commands and the actual file paths the binary writes, so you can verify each stage before moving on to the next.

shellm is not a server. It does not run as a daemon, it does not listen on any port, and it does not modify your ~/.ssh/ directory except through the explicit ssh-keygen calls you initiate from the Keys & Agent tab. What it does is generate ssh command lines from the profile fields you fill in, wrap them in ~/.shellm/.runfiles/runproc.<ts> shell scripts, and exec your configured terminal emulator to run them. If something goes wrong, the runner scripts and a trace log are left on disk for inspection — see the Troubleshooting section at the end of this document.

Prerequisites

You need a Linux desktop (or macOS, with caveats) with Rust 1.80 or later, the iced 0.13 system development headers, and at least one terminal emulator installed. The build has been verified on Debian 12, Ubuntu 24.04, Fedora 40, and Arch Linux as of mid-2026. On macOS, iced 0.13 builds but the resulting app runs under Rosetta on Apple Silicon and several of the modern terminals in shellm's terminal list (Foot, kgx, xfce4-terminal) are not available — use Alacritty, Kitty, or WezTerm instead.

You also need an SSH client (ssh, scp, sftp, ssh-keygen, ssh-agent, ssh-add) installed and on your PATH. shellm execs these by name; the default config points at the bare names ssh, scp, etc., which resolve through PATH lookup. If your SSH installation lives in a non-standard location (Homebrew on macOS, Nix, conda), open the Configs tab after first run and set the absolute paths explicitly. OpenSSH 8.0 or later is recommended; shellm's SCP browser uses sftp -b - batch mode for remote operations, which requires OpenSSH 5.4 or later for the rm command to work on directories.

A working SSH target is helpful for the first run — a VPS, a home server, a Raspberry Pi, anything you can already SSH to with a password or a key. If you don't have one handy, you can still walk through the first three steps of this guide (install, build, first run) and create a profile pointing at localhost, which is enough to verify the binary works.

Step 1: Install the Build Dependencies

On Debian or Ubuntu, install the iced 0.13 system development headers:

sudo apt update
sudo apt install -y build-essential pkg-config \
    libx11-dev libxext-dev libxft-dev libxinerama-dev \
    libxcursor-dev libxrender-dev libxfixes-dev libxrandr-dev \
    libdbus-1-dev libudev-dev libwayland-dev libgl-dev \
    libglib2.0-dev libcairo2-dev libpango1.0-dev \
    libgdk-pixbuf2.0-dev libatk1.0-dev libgtk-3-dev

On Fedora, the package names are slightly different — mesa-libGL-devel instead of libgl-dev, gdk-pixbuf2-devel instead of libgdk-pixbuf2.0-dev, and so on. The full Fedora equivalent is:

sudo dnf install -y gcc pkg-config \
    libX11-devel libXext-devel libXft-devel libXinerama-devel \
    libXcursor-devel libXrender-devel libXfixes-devel libXrandr-devel \
    dbus-devel libudev-devel wayland-devel mesa-libGL-devel \
    glib2-devel cairo-devel pango-devel gdk-pixbuf2-devel \
    atk-devel gtk3-devel

On Arch Linux, the gtk3 and cairo packages pull in everything else as dependencies:

sudo pacman -S --needed base-devel pkgconf gtk3 cairo pango

On macOS, the Homebrew toolchain is sufficient — install Xcode Command Line Tools and Homebrew, then brew install cairo pango. The build will use the tiny-skia software renderer by default, so no GPU framework is required.

Step 2: Install Rust

Install Rust stable 1.80 or later via rustup. The version shipped in Debian 12's apt repository (1.63 as of mid-2026) is too old for iced 0.13; you need rustup.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustc --version
# -> rustc 1.8x.0 (something >= 1.80)

If you already have rustup installed, run rustup update stable to make sure you are on a recent toolchain.

Step 3: Build shellm

Extract the 1.1.0 release tarball and build the release binary. The build takes about 90 seconds on a modern laptop with the tiny-skia software renderer; a full GPU build with wgpu enabled (not the default) takes about three minutes.

tar -xjf shellm-1.tar.bz2
cd shellm-1.1
cargo build --release
# -> ./target/release/shellm

The first build downloads and compiles all dependencies — iced, tokio, serde, toml, chrono, regex, and so on. Subsequent builds are incremental and take a few seconds. If the build fails on a missing system library, double-check Step 1 — iced 0.13's compiler error messages are not always explicit about which system package is missing, but the package list above is the complete set on Debian/Ubuntu.

You can install the binary system-wide if you prefer, but it's not required:

sudo cp ./target/release/shellm /usr/local/bin/
# Or, if you use cargo's install path:
cargo install --path .

Step 4: First Run

Run the binary:

./shellm

On first run, shellm calls ensure_shellm_tree() from src/data/paths.rs, which creates ~/.shellm/ with mode 0700, creates ~/.shellm/profiles/ and ~/.shellm/.runfiles/, writes a default config to ~/.shellm/config, writes the version marker to ~/.shellm/.init, and opens the main window. The window defaults to 960×640 pixels with a minimum size of 800×540 — wide enough to fit the Profiles tab's three-column layout (profiles list + SSH options + Connection fields) without truncating the rightmost input fields, and tall enough to show all checkboxes and forwarding controls without scrolling.

You should see the Connections tab as the active tab. The agent indicator at the top right shows a red dot with the label "No Agent" — this is correct, no agent has been launched yet. The status bar at the bottom shows the version string ("shellm 1.1.0") and is otherwise empty. The menu bar at the top has the standard entries (File, Edit, Profile, Keys, Options, Help) and the tab bar has five entries: Connections, Profiles, Keys & Agent, SCP Browser, Configs.

If the window does not open, check ~/.shellm/.runfiles/trace.log for an error message. The most common first-run failure is a missing terminal emulator — shellm tries to auto-detect a terminal from the fallback chain described in src/data/terminal.rs (rs-mrxvt → alacritty → kitty → wezterm → ghostty → warp → tabby → foot → kgx → rxvt-unicode → xfce4-terminal → mrxvt → xterm), and if none of those are on PATH, the Configs tab will warn you but the main window will still open.

Step 5: Create a Profile

Switch to the Profiles tab and click New. Fill in the fields:

Field	Value	Notes
Title	`my-server`	Display name; used as the filename for `~/.shellm/profiles/my-server.profile`
Host	`your.server.example.com`	Or an IP address
User	`your-username`	Check "Ask" if you want to be prompted at connect time
Port	`22`	The default; change if your server runs SSH on a non-standard port
Identity	(leave blank for password auth)	Click the file picker to select a private key from `~/.ssh/`
Compression	`On`	Useful on slow links; harmless on fast ones
Compression Level	`6`	The OpenSSH default
All other fields	(defaults)	The defaults match the original secpanel's `default.profile`

Click Save. The profile is written to ~/.shellm/profiles/my-server.profile as TOML. Switch back to the Connections tab — you should see your new profile in the list with the title and user@host on two lines.

Step 6: Connect

Click the profile row to select it, then click Connect. shellm builds the SSH command line via build_ssh_command() in src/ssh/command.rs, writes a runner script to ~/.shellm/.runfiles/runproc.<unix-timestamp>, writes a wrapper script to runproc.<unix-timestamp>-run that execs your configured terminal with the runner script as its argument, and execs the wrapper. A new terminal window should open with an SSH session to your server.

If the connection fails, the terminal window will close immediately and the error message will be in the terminal's scrollback (if your terminal has one) or in ~/.shellm/.runfiles/trace.log. The most common failure on first run is a hostkey mismatch — OpenSSH refuses to connect to a host whose hostkey has changed since the last connection, and the error message points you to ssh-keygen -R <host> to clear the old entry. shellm's Keys & Agent tab has a hostkeys browser that does this for you: open it, find the offending entry, click Delete.

If you checked Ask on the User field in the profile, a modal dialog appears when you click Connect asking for the username. Type it and press Enter; the connect proceeds. If you have an Identity file set and it has a passphrase, your SSH agent (if running) handles the prompt — or, if no agent is running, ssh-askpass is invoked. Make sure one of ssh-askpass, x11-ssh-askpass, or ksshaskpass is installed and pointed at by the SSH_ASKPASS environment variable; otherwise the passphrase prompt may not appear and the connection will hang silently.

Step 7: Use the SCP Browser

Switch to the SCP Browser tab. Click the profile picker at the top, select your connected profile, and click Connect. The status indicator turns green and shows user@host:port; the right pane populates with the remote home directory listing. The left pane shows your local home directory by default.

Click on a directory in either pane to navigate into it (Midnight-Commander-style single-click navigation). Click on the .. entry at the top to go up one level. The toolbar buttons above each pane provide up/refresh/new-folder/delete operations. The path bar above the file list accepts a typed path — type /var/log and hit Enter (or click Go) to jump there directly.

To transfer a file, click on it in the source pane to select it. The Upload button (the large → arrow in the center column) activates if a file is selected on the left pane and you are connected; the Download button (the ← arrow) activates if a file is selected on the right pane and you are connected. Click the arrow to transfer. The destination pane auto-refreshes after the transfer completes, and the status bar shows the result ("Uploaded myfile.txt (12.3 KB)" or similar). Directories are auto-detected and transferred recursively — scp -r is used automatically.

All SCP browser operations run in tokio::task::spawn_blocking, so the UI stays responsive during long transfers. The orange busy dot in the status bar shows when an operation is in flight; you can switch to other tabs while a transfer is running, but starting a second transfer before the first completes will queue it (the SCP browser is single-threaded per connection by design — sftp does not support concurrent operations on a single channel).

Step 8: Generate a Keypair

Switch to the Keys & Agent tab. Click Generate Keypair. In the dialog that appears:

Field	Value	Notes
Type	`RSA`	Or DSA, or RSA1 (the original SSH v1 protocol)
Bits	`4096`	2048 is the minimum recommended; 4096 is the modern default
File	`~/.ssh/id_rsa_new`	The `.pub` extension is added automatically to the public key
Passphrase	(your choice)	Empty for no passphrase (not recommended)
Comment	`your-email@example.com`	Appears in the public key file and in `authorized_keys` entries

Click Generate. shellm invokes ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_new -N "passphrase" -C "your-email@example.com" and reports the result. The new keypair appears in the keypair list, and you can click Info to view the fingerprint and bubblebabble representation. To use the new key with a profile, switch to the Profiles tab, edit the profile, and set the Identity field to the new private key path.

Step 9: Distribute Your Public Key

Still on the Keys & Agent tab, click Distribute Key. A wizard opens:

Pick the public key to distribute (defaults to your default identity, or the most recently generated key).
Pick the targets — a multi-select list of your existing profiles. You can select multiple targets; the wizard generates one key-distribution script that runs against all of them sequentially.
Review the generated script. The script uses ssh to check whether the public key is already in ~/.ssh/authorized_keys on each target, and appends it only if it's not — mkdir $HOME/.ssh 2>/dev/null; grep "$(cat <pubkey>)" $HOME/.ssh/authorized_keys > /dev/null 2>&1 followed by an if branch that either skips (already present), reports a connection error (exit code 255), or appends the key with the correct permissions (cat >> $HOME/.ssh/authorized_keys; chmod 600 $HOME/.ssh/authorized_keys; chmod 700 $HOME/.ssh).
Run — the script is written to ~/.shellm/.runfiles/runproc.<ts> and launched via the configured terminal. You will be prompted for the password on each target host (unless you already have key-based auth set up, in which case the script just verifies presence).

This finishes a stub that was present in the original secpanel 0.6.1 — the wizard UI existed, but the final "Run" step was never wired up. shellm wires it up via build_keydist_script() in src/ssh/command.rs and the standard launch_interactive runner.

Troubleshooting

The terminal does not open when I click Connect. The most common cause is that the configured terminal emulator is not installed. Open the Configs tab and check the availability indicators next to each terminal in the dropdown — the ones with a red dot are not on your PATH. Pick one with a green dot, click Save, and try Connect again. If you are on a headless server with no terminal emulator at all, shellm cannot open a connection — it relies on a terminal to display the SSH session. Install xterm as a minimum.

The connection fails immediately with "Host key verification failed". The host's hostkey has changed since your last connection. Open the Keys & Agent tab, find the hostkey browser, locate the offending entry, and click Delete — this runs ssh-keygen -R <host> for you. Alternatively, set the profile's "Strict hostkey" checkbox to off (not recommended for production use).

The SCP browser shows "ssh: command not found" or "sftp: command not found" when I click Connect. By default the SCP browser uses ssh for remote list/mkdir/delete operations and scp for file transfers — both must be on your PATH. If you have switched to the sftp -b - backend in the Configs tab (for restricted sshd configs that disable shell access), the sftp binary must also be on PATH. Open Configs and check the SSH binary and SCP binary fields; switch the SCP browser backend back to scp + ssh (the default) if you do not need sftp.

My settings are not saved between runs. Check that ~/.shellm/config is writable. If you ran shellm as root by accident (or with sudo), the ~/.shellm/ directory may be owned by root and your user cannot write to it. Fix with sudo chown -R $USER:$USER ~/.shellm/.

The GPG data protection prompts for a passphrase on every launch. This is by design. shellm does not cache the GPG passphrase — if protectdata is on, the entire ~/.shellm/ tree is encrypted into spdata.lck on exit and decrypted on launch. If this is too intrusive, turn off Protect in the Options menu and your data will be stored in plaintext TOML (the same as the original secpanel).

I'm on macOS and the build fails with "linking with cc failed". Install Xcode Command Line Tools (xcode-select --install) and Homebrew's cairo and pango packages. The iced 0.13 macOS build is finicky about library paths; cargo build --release should pick them up automatically via pkg-config, but if not, set PKG_CONFIG_PATH=/opt/homebrew/lib/pkgconfig (Apple Silicon) or /usr/local/lib/pkgconfig (Intel) before the build.

Where to Go Next

README.md — full feature list, architecture overview, and credits.
blog.md — long-form technical walkthrough of the design decisions, including why the data directory is ~/.shellm/, why the SCP browser defaults to ssh+scp (with sftp -b - as an opt-in backend) instead of a Rust SFTP library, and why there is no TLS anywhere in the stack.
LICENSE — the full GPLv2 text and the copyright disclaimer that applies to shellm and to the original secpanel.

shellm 1.1.0 quickstart — Jeremy Anderson, dcos.net, 2026 — GPL-2.0-or-later. Original secpanel © Steffen Leich-Nienhaus, GPL-2.0-or-later. This document walks through the install, build, first-run, and basic usage flow as shipped in the 1.1.0 release.

18 KiB Raw Permalink Blame History Unescape Escape