Fri January 5, 2024

Installation

Thank you for trying Hucksh!

Installation overview

Hucksh is a single executable, with several subcommands, like git. The distribution tarball has these files in it (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
  • hucksh-edit
  • huckshrc

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.

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

Table of Contents

[ TODO ]

Download hucksh

Download hucksh for your OS from Dropbox, here: https://www.dropbox.com/scl/fo/xnri6keqt3zl27g07d54i/h?rlkey=zx44netkcb4pj8hax1773twk5&dl=0

macOS install & startup, server & client local

macOS install

After unpacking the distribution 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 -dbName/-d 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 good for 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 way licenses work is subject to change.

Start the server

You currently have to start the server by hand, in a terminal. 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.

Start the client

Starting the client via the finder

Once you’ve started the server (see above), open the Finder, navigate to /Applications, and double-click on the hucksh app.

Starting the client via the command-line

(Don’t use sudo here, either.)

hucksh gui

As above, you can add a -v option to get some logging, e.g. hucksh gui -v.

Linux install & startup, server & client local

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 12mb smaller than the version with the GUI.

Linux startup

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

Start the server

You currently have to start the server by hand, in a terminal. 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.

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.

Starting the client via the command-line

(Don’t use sudo here, either.)

hucksh gui

As above, you can add a -v option to get some logging, e.g. hucksh gui -v.

Remote usage

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 may eventually write a hucksh subcommand to make this easier, but haven’t yet. Let me know if this would interest you.)

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. You don’t have to name them the way I have, of course, but be advised that $HOME/.hucksh.socket is the default name of the Unix socket that the server listens on.

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.
hucksh serve --verbose

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) to select the connection from a list. (Requires a license.)

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.