Fri January 5, 2024 Larry Clapp

Installation

Home » Hucksh(ell) » Hucksh Documentation » Installation

Thank you for trying Hucksh!

Installation overview

Hucksh is a single executable, with several subcommands, like git. The distribution tarballs have these files in them (among others):

  • linux
    • hucksh – Linux server, gui client (Wayland & X11), and cli
    • hucksh.server – Linux server, cli (no GUI code)
  • macos
    • hucksh.app – macOS application bundle, with server, gui client, and cli
  • windows
    • hucksh.exe – Windows exe file, with gui client & cli (no server)
  • hucksh-edit (not in Windows version yet)
  • huckshrc (not in Windows version yet)

Generally speaking, you run the appropriate install script for your OS, accept the EULA, optionally install a license, run “hucksh serve”, and then run “hucksh gui” locally with the appropriate arguments to connect to it and start the GUI. Alternatively, you can just click on the app in a file browser, and it will start the GUI and also auto-start the server in the background, if it’s not already running.

Windows does not yet support the “serve” subcommand; see below about how to configure the GUI to use a remote server.

When the server and the gui are on the same machine, they can talk to each other directly (without using ssh/hucksh forward). When they’re on different machines, you currently need to tunnel the connection via ssh or hucksh forward. More on that below.

Download hucksh

Download hucksh for your OS from the hucksh_public repository at Github, here: https://github.com/HuckRidgeSW/hucksh_public/releases

macOS install & startup, with local server & client

macOS install

After unpacking the macOS tarball:

cd ./macos
./install-macos

Optional

Add the hucksh binary directory to your $PATH:

PATH=$PATH:/Applications/hucksh.app/Contents/MacOS

The below instructions assume you’ve done this.

macOS startup

Accept the EULA

If you don’t accept the EULA, the server won’t run. The EULA is here: Hucksh EULA.

hucksh eula --accept

Accepting the EULA (and installing a license; see below) are recorded in the server database. Thus, if you start the server and configure a different database (via the -d/--dbName flag), you must accept the EULA (and install the license) again, for that database.

Optional: Install a license

You can purchase a license here: https://huckridgesw.onfastspring.com/hucksh-license. If you don’t install a license, the server will run in trial mode, which means the GUI will only open two shell tabs, and only a single top-level window at a time.

hucksh license -l <license-file>

See above about accepting the EULA and installing a license per server database.

A license is perpetual with a year of upgrades. For example, if you buy a license on December 1, 2023, it’ll be good for all older versions and any version released for the following calendar year, i.e. through November 30, 2024. Starting December 1, 2024, newer code will stop working with that license and will run in trial mode. Older code will keep working with that license.

The same license works on both macOS and Linux versions. (The server doesn’t run on Windows yet and thus no license is required there.)

The way licenses work is subject to change.

Start the server

You can start the server in a terminal, but don’t have to. (If you don’t, the GUI will auto-start one if it can’t connect to one.) Do not use sudo. Unlike sshd, the hucksh server must run under your own ID.

# assumes you've added hucksh to your $PATH; see above
hucksh serve # do not use sudo

You can also add a -v option to get some logging, e.g. hucksh serve -v.

Use of tee: use -i

If you want to save the logging with tee, remember to use the -i argument, so that if you abort the server with ^C, tee ignores the SIGINT and waits for the pipe from hucksh to finish. (The server does some cleanup after ^C, and some logging, and if you don’t use tee -i, the ^C will kill the tee before the server can finish, and it won’t be able to do its cleanup, because it can’t log about it.)

hucksh serve -v --slog - |& tee -i ~/.hucksh.server.log

Start the client

Starting the client via the finder

Open the Finder, navigate to /Applications, and double-click on the hucksh app. If the server is running already (e.g. see above), the client will connect to it and start up. If it’s not, the client will start one itself, and proceed.

Starting the client via the command-line

(Don’t use sudo here, either.)

hucksh gui

or (for example)

hucksh gui -v --glog - |& tee -i ~/.hucksh.gui.log

As above, you can add a -v option to get some logging, e.g. hucksh gui -v. If you tee the output to a file, please use tee -i, as described above for the server.

Linux install & startup, with local server & client

Linux install

After unpacking the distribution tarball:

cd ./linux
./install-linux

Option: The install script copies the version of hucksh that has the GUI code. If you’ll only be running the server, copy hucksh.server to ~/bin/hucksh instead. As of this writing, the server-only code is about 10mb smaller than the version with the GUI.

$PATH

The below instructions assume that hucksh has been copied to $HOME/bin (the install script does this) and that $HOME/bin is in your $PATH.

Linux startup

(If you’ve read through from the top, this section is very similar to the macOS section.)

Accept the EULA & (optionally) install a license

See the EULA & License sections above.

Start the server

You can start the server in a terminal, but don’t have to. (If you don’t, the GUI will auto-start one if it can’t connect to one.) Do not use sudo. Unlike sshd, the hucksh server must run under your own ID.

# assumes you have $HOME/bin (or wherever you put it) in your $PATH
hucksh serve # do not use sudo

You can also add a -v option to get some logging, e.g. hucksh serve -v.

Use of tee: use -i

If you want to save the logging with tee, remember to use the -i argument, so that if you abort the server with ^C, tee ignores the SIGINT and waits for the pipe from hucksh to finish. (The server does some cleanup after ^C, and some logging, and if you don’t use tee -i, the ^C will kill the tee before the server can finish, and it won’t be able to do its cleanup, because it can’t log about it.)

hucksh serve -v --slog - |& tee -i ~/.hucksh.server.log

If the server doesn’t start, see above about accepting the EULA and (optional) installing a license.

Start the client

Starting the client via a file browser

Once you’ve started the server (see above), open a file browser, navigate to ~/bin, and double-click on the hucksh app. As mentioned above, if the client can’t connect to a local server, it’ll start one itself.

Starting the client via the command-line

(Don’t use sudo here, either.)

hucksh gui

or (for example)

hucksh gui -v --glog - |& tee -i ~/.hucksh.gui.log

As above, you can add a -v option to get some logging, e.g. hucksh gui -v. If you tee the output to a file, please use tee -i, as described above for the server.

Windows install

The Windows installation is still somewhat manual, I’m afraid. Copy hucksh.exe to somewhere in your path, preferably something like C:\Program Files\Hucksh\hucksh.exe.

See below about how to run it.

Remote usage, Mac/Linux ➡️ Mac/Linux

The hucksh client and server communicate over a Unix socket, typically $HOME/.hucksh.socket (for local usage) or $HOME/.hucksh.socket.$TARGET for remote usage.

For remote usage, the Unix socket on the local machine is forwarded to the socket on the remote machine via ssh. (I’ll probably eventually connect directly to a remote system via an internal ssh client.)

As mentioned above, copy the appropriate executable to your target. If you’re on Linux and copying hucksh.server, rename it to just hucksh.

For these instructions, I’ll assume that you’re on a Mac, targeting a Linux machine called “remote”.

The below commands copy the Linux executable over to the remote machine, start a screen session, and start the server inside the screen session.

The -o ... -L ... arguments on the ssh command line forward the data written on the Unix socket $HOME/.hucksh.socket.remote to the given Unix socket on the target. Technically, you don’t have to name them the way I have, of course, but the “new connection” window assumes that you have.

Copy over the server and start it up

# Copy the server over
scp linux/hucksh.server remote:bin/hucksh

# ssh over, forwarding the given Unix socket over the ssh connection.
# "<remote-$HOME>" should be $HOME for your user ID on the remote machine.
# Note that to use -L for Unix sockets, you must use full paths, and that
# tilde-expansion doesn't work.
ssh -o 'StreamLocalBindUnlink=yes' \
    -L $HOME/.hucksh.socket.remote:<remote-$HOME>/.hucksh.socket \
    remote

# (on 'remote') Start a screen session (or tmux, as you wish)
screen -dR hucksh

# Start the hucksh server in "verbose" mode, logging to stdout.
hucksh serve --verbose --slog -

Start the local client

Start the GUI and tell it to use the Unix socket that you’ve forwarded over the ssh connection to the remote target.

hucksh gui --address unix:$HOME/.hucksh.socket.remote --verbose

If you already have the gui running, you can press Cmd-Opt-Shift-N (or Ctrl-Alt-Shift-N on Linux/Windows) to select the connection from a list. (Requires a license.)

You can also say

hucksh gui -a ""

to open the “choose a connection” window from the get-go.

Remote usage, Windows ➡️ Mac/Linux

Windows is somewhat tricky. The stock Windows ssh client doesn’t forward Unix sockets. So you can either use hucksh forward to do the forwarding, or install Cygwin and the Cygwin ssh client, and use that. The hucksh gui will work with either.

(First make sure you can ssh without entering a password to your target. This should get known_hosts and so on configured.)

See hucksh forward --help for more details on that command. See above for instructions on how to use ssh. See https://cygwin.com/ for information about Cygwin.

To replicate the ssh session outlined above with hucksh forward, use

hucksh forward remote

This will use all the default settings to try to open an internal ssh client to remote, create $HOME/.hucksh.socket.remote, and send data from that socket to <your-id>@remote:$HOME/.hucksh.socket.

A note about forward and ssh: This subcommand uses $HOME/.ssh/known_hosts and (by default) $HOME/.ssh/id_rsa for the identify file. It does not support password entry or passphrase entry for encrypted keys. If you can’t ssh to the remote system without entering a password (for the remote host) or passphrase (for your private key), this subcommand won’t work.

Note that hucksh is not Cygwin-aware and in particular does not understand Cygwin paths. Cygwin ssh, of course, is and does. So to use hucksh with Cygwin ssh, you’ll need to use cygpath -w on the hucksh socket pathname:

# Cygwin ssh, inside a Cygwin shell
% ssh -v -L $HOME/.hucksh.socket.host:/Users/your_id/.hucksh.socket 10.0.2.2
[ ... ]
debug1: Local connections to /home/your_id/.hucksh.socket.host:-2 forwarded to remote address /Users/your_id/.hucksh.socket:-2
[ ... ]

# Hucksh call, likewise inside a Cygwin shell
% hucksh gui -v --address unix:$(cygpath -w $HOME/.hucksh.socket.host)
2024/02/29 15:48:48.686431 Dialing server at unix:C:\cygwin64\home\lmc\.hucksh.socket.host
[ ... ]

Caveats

  • As mentioned online, the GUI supports only limited cut-and-paste of the command output. You can select only single lines of contiguous text that all shares the same attribute (e.g. color, boldness, etc). You can use the buttons in the command widget to copy all the output, though. And you can do full text selection in the command entry widget.
  • The command editor uses the stock Gio editor widget, which is pretty basic.

Possible problems with old Linux installations

(This section is experimental. It worked for me, though I no longer have a Linux system where it’s necessary (or where I can test it).)

Hucksh is compiled with Go 1.21, and it expects a fairly recent glibc. Some Linux machines don’t have what hucksh expects, and you get an error similar to this:

% bin/hucksh.server serve
bin/hucksh.server: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.28' not found (required by bin/hucksh.server)

To get around this (assuming you can’t just upgrade your libc6 package), it turns out you can tell Linux to use a version of libc that you give it:

% cat linux/hucksh-for-old-linux
#!/bin/bash

# Note that $ORIGIN is not an environment variable, it's expanded by
# ld-linux-x86-64.so.2 (which is why it's quoted).  See
# <https://man7.org/linux/man-pages/man8/ld.so.8.html>.

exec ~/bin/hucksh-libs/ld-linux-x86-64.so.2 --library-path '$ORIGIN/hucksh-libs' \\\\
     ~/bin/hucksh.linux "$@"
% cp -p linux/hucksh ~/bin/hucksh.linux
% cp -p linux/hucksh-for-old-linux ~/bin/hucksh
% tar -C linux -cf - hucksh-libs | tar -C ~/bin -xf -

And then only run hucksh using that shell script instead of directly.

The hucksh-for-old-linux script and the hucksh-libs tree are included in the hucksh distribution. Only use them if you need to. There’s nothing special or weird about them; I pulled them off my own Debian Linux VM.

Again, this section is experimental and might not work perfectly or at all, though it does work for me.