Start here

Download a binary from GitHub Releases, or run the installer. It works on macOS and Linux, on both Intel and ARM:

curl -fsSL https://raw.githubusercontent.com/0xcd21h/borg-commander/main/scripts/install.sh | sh

The installer verifies the archive checksum and puts borg in a folder on your PATH, so you can run it straight away in the same terminal. It picks ~/.local/bin if that is already on your PATH, then /usr/local/bin if it is writable (for example as root in a container), and otherwise uses ~/.local/bin and adds it to your shell’s startup file. When it finishes, it starts borg; set BORG_NO_RUN=1 to skip that, or BORG_INSTALL_DIR to choose the folder. If the same version is already installed, running the installer again skips the download.

The installer can also set borg up as a service that starts at boot. The service is optional. With it, sessions you keep with borg service keep NAME stay running with no terminal open, and a paired computer reaches this machine after a restart. In a terminal the installer asks once before it starts borg, and the default answer is n. Set BORG_SERVICE=1 to set the service up without the question, as in an unattended install, or BORG_SERVICE=0 to skip the question. The setup runs borg service install, enable and start, which use sudo unless you are root. Without a terminal and without the variable, the installer leaves the service alone. You can set it up later inside borg, from F9 → Remote → Background service…. Where systemd or launchd is missing, as in most containers, the installer skips the step and says why. If the setup fails, borg stays installed and the installer prints the commands to finish by hand. On Linux, the root part of the watcher stays a separate step: install it with borg service watch install when you want it.

To build from source, you need Rust 1.97 or newer:

cargo install --locked --git https://github.com/0xcd21h/borg-commander borg-app

On Linux, the build also compiles the process watcher’s eBPF programs, which need a nightly compiler and bpf-linker. When they are missing, the build stops and prints the two commands that install them. To build without the programs, set BORG_NO_EBPF=1. The watcher then hears the kernel’s process events instead:

BORG_NO_EBPF=1 cargo install --locked --git https://github.com/0xcd21h/borg-commander borg-app

Homebrew support is ready and will work once the tap is published:

brew install 0xcd21h/tap/borg-commander

Run borg in the folder you want to browse. F10 quits, and Ctrl-O switches from the console back to the panels. To update, run borg update for a downloaded copy, or use Homebrew or cargo if you installed it that way. Borg installs an update only when the release carries the project’s signature. If the signature is missing or wrong, the copy you have stays as it is. borg --version prints the installed version. Open sessions move to the new version and keep their shells (see Updating with sessions open).

Once a day, Borg looks for a new release. When one is out, Borg offers it once the panels show and you have not touched the keyboard or mouse for 2 seconds. Enter runs borg update in Borg’s shell, or the Homebrew or cargo command when one of those installed Borg. S skips that version, and Borg offers the next one once it is out. Esc closes the offer, and Borg asks again a day later. N turns the daily check off by setting update-check = false in the config, and update-check = true turns it back on. Borg keeps the time of the last check and the version you skipped in update-check in its state folder.