Installation

mirrorball ships as a single compiled binary with no runtime dependencies. Pick whichever channel fits how you already install things; they all end up with the same executable.

The command you type is mirb. Every channel also installs mirrorball as a second name for the same binary — a symlink on macOS and Linux, a tiny .cmd shim on Windows, a second bin entry under npm — so whichever name you remember is the one that works.

Requirements

Bun is not required to run a released binary. It is only needed if you build from source.

If ssh is missing, mirrorball says so with the NO_SSH error code rather than failing obscurely:

mirb: error: no ssh binary found on PATH
mirb: hint: Install OpenSSH, or point mirb at one with MIRB_SSH=/path/to/ssh.

The install script

macOS and Linux:

curl -fsSL https://mirb.dev/install.sh | sh

Windows (PowerShell):

irm https://mirb.dev/install.ps1 | iex

The script detects your platform, resolves the latest release, downloads the matching archive, verifies its SHA-256 against the release's checksums.txt, and installs the binary. Verification is not optional and there is no switch to skip it — a flag that turns integrity checking off is a flag an attacker can talk someone into typing.

Afterwards you have both names on your PATH:

$ mirb --version
mirb v0.1.0
$ mirrorball --version
mirb v0.1.0

On macOS and Linux, mirrorball is a symlink pointing at mirb in the same directory. On Windows it is a mirrorball.cmd shim that forwards to mirb.exe, because a symlink there would need administrator rights or developer mode. Either way the alias is best-effort: if it cannot be created — an unwritable directory, or an unrelated mirrorball already sitting in the way — the install of mirb still succeeds.

Options

The shell installer takes flags or environment variables:

curl -fsSL https://mirb.dev/install.sh \
  | sh -s -- --version 0.1.0 --dir /usr/local/bin

The PowerShell script takes the same ideas as parameters:

irm | iex cannot forward parameters, so pass them through a script block or the environment:

& ([scriptblock]::Create((irm https://mirb.dev/install.ps1))) -Version 0.1.0

$env:MIRB_VERSION = '0.1.0'; irm https://mirb.dev/install.ps1 | iex

Notes

• Alpine and other musl systems. The release binaries are compiled against glibc. The installer warns rather than refuses, because gcompat makes them work often enough that a hard stop would be wrong. If mirb will not start, install gcompat or build from source.
• PATH. If the install directory is not already on your PATH, the script prints the exact line to add and the exact file to add it to, chosen for your shell.
• Replacing a running binary. The installer stages the new binary and rename(2)s it into place, so an upgrade during a live background session does not hit ETXTBSY and does not disturb the running process.

Is there an npm package?

Not currently. npm rejected both candidate names — mirb and then mirb-cli — under its similarity check on new package names, which compares against existing packages (mitt, mime, mri, sirv-cli) and is unrelated to whether a name is free.

Rather than publish under a name nobody would guess, mirrorball ships through the install script and the GitHub Releases page. Both give you the same binary, verified against the same checksums.txt.

From source

You need Bun 1.3 or newer. Node is not supported: mirrorball uses Bun-native APIs (Bun.spawn, Bun.TOML, Bun.stringWidth, Bun.which, Bun.color) with no Node equivalent worth shimming.

git clone https://github.com/heysanil/mirrorball-cli.git
cd mirrorball-cli
bun install
bun run build          # standalone binary for this machine -> ./dist/mirb

bun run build compiles for the host platform only. bun run build:all cross-compiles all five release targets. Put the result somewhere on your PATH:

install -m 755 dist/mirb ~/.local/bin/mirb
mirb --version

A source build produces the mirb binary only. If you want the long name too, add the symlink yourself:

ln -sf mirb ~/.local/bin/mirrorball

To run straight from the source tree without compiling, the entry file is mirb.ts:

bun /path/to/mirrorball-cli/mirb.ts 10.0.0.7 3000

If you are going to work on mirrorball rather than just with it, use bun link and read Development instead — it covers the dev loop, the test harness, and the conventions the codebase holds to.

Verifying a download by hand

Every release publishes a checksums.txt alongside the archives. To check an asset yourself:

VERSION=0.1.0
BASE=https://github.com/heysanil/mirrorball-cli/releases/download/v$VERSION

curl -fsSLO $BASE/checksums.txt
curl -fsSLO $BASE/mirb-$VERSION-darwin-arm64.tar.gz

sha256sum --ignore-missing -c checksums.txt

On macOS without GNU coreutils:

shasum -a 256 mirb-$VERSION-darwin-arm64.tar.gz
grep darwin-arm64 checksums.txt

Asset names follow mirb-<version>-<os>-<arch>.tar.gz, except Windows which ships .zip.

Then confirm what you installed:

$ mirb --version
mirb v0.1.0

(Piped or redirected, that same command emits JSON — mirrorball switches to machine output whenever stdout is not a terminal.)

Upgrading

To pin or roll back, pass a version:

curl -fsSL https://mirb.dev/install.sh | sh -s -- --version 0.1.0

Background sessions are supervised by the mirb process that started them, not by the binary on disk, so an upgrade does not disturb a running tunnel. The next mirb ls you run is the new build reading the old build's records — which is fine, because session records are validated permissively on read for exactly this reason.

Uninstalling

Remove the binary and its alias:

rm ~/.local/bin/mirb ~/.local/bin/mirrorball   # or wherever --dir put them

Remove-Item "$env:LOCALAPPDATA\mirb\bin\mirb.exe"
Remove-Item "$env:LOCALAPPDATA\mirb\bin\mirrorball.cmd"

Then, if you want mirrorball gone completely, remove its config and state:

rm -rf ~/.config/mirb                # profiles
rm -rf ~/.local/state/mirb           # session records and logs

Stop any background sessions first — mirb stop --all — or you will leave orphaned supervisor processes holding local ports with nothing left to manage them.

Where files land

XDG_CONFIG_HOME and XDG_STATE_HOME are honoured where set. $MIRB_CONFIG points at a config file directly, and $MIRB_STATE_DIR replaces the state root wholesale — handy for running two isolated instances on one machine. The full list of environment variables is in Environment.

mirrorball creates nothing until you use it. No config file is required; a missing one is the common case, not an error.

Next

• Quick start — a working tunnel in thirty seconds.
• Concepts — the vocabulary, and the readiness model.