matterbox / Docs / Installation

Installation

One line on Linux and macOS. This is the long version of it: what that line actually does, every way round it, and the two things it leaves for you to turn on.

matterbox installs per user. Nothing needs root, nothing lands outside your home directory, and there is no daemon running until you ask for one. The binary is a single static-ish executable in ~/.local/bin; the state it keeps — config, token, message cache — lives under ~/.config/matterbox and is not touched by installing or removing it.

The one-line install

$ curl -fsSL https://matterbox.work/install.sh | sh

It downloads the release binary and checks it against the checksums.txt the release publishes. The published binaries carry FFmpeg inside them, so inline video and the HEIC/AVIF/JPEG XL image formats are already in one — statically linked, nothing to install alongside. That leaves a single difference between downloading and compiling: the --demo soundtrack needs ALSA at runtime, which a static binary cannot load, so only a source build has it. Pass --source for that; a platform the releases do not cover builds from source by itself. It says which path it took, and which features went in.

The source build tracks the latest release tag, not the default branch, so both paths mean the same version of matterbox. Before the first release there is no tag to take and the default branch is what gets built — which is what a clone and a make install would have given you anyway.

Flags, and the variables

Because the script arrives on standard input, flags need sh -s -- in front of them:

$ curl -fsSL https://matterbox.work/install.sh | sh -s -- --prebuilt

The variables exist for piped runs, where sh -s -- is awkward to remember and awkward to read in someone else's setup script:

$ curl -fsSL https://matterbox.work/install.sh | MATTERBOX_PREBUILT=1 sh
$ curl -fsSL https://matterbox.work/install.sh | MATTERBOX_VERSION=v1.0.0 sh

What it checks first

A downloaded binary is verified against the checksums.txt the release publishes, using whichever of sha256sum, shasum or openssl the machine has. If none of them is present, or the checksum file cannot be fetched, the installer stops rather than install something it could not check. A mismatch is a hard error and tells you not to use the download.

The releases cover Linux and macOS on amd64 and arm64. Anything else has to build from source — the installer says so rather than guessing at an asset name. On an Apple Silicon Mac it also asks the kernel whether it is being translated, because a shell running under Rosetta reports x86_64 and would otherwise be handed the slow binary for the rest of its life.

Where things land

Which completion script it writes depends on your $SHELL, so it writes one, not four. If a different matterbox already comes earlier on your PATH, the installer says so and names it — that one, not the new one, is what would run.

From source

$ git clone https://github.com/cornedor/matterbox
$ cd matterbox
$ make install

make install is the fuller of the two routes. It builds with whatever optional features this machine can compile, installs to ~/.local/bin, writes the completion script for your shell, registers the mmauth:// handler on Linux, and drops the listen service in place — disabled. It also appends the fpath lines to ~/.zshrc if they are not there, which the piped installer will not do.

Plain Go works too, and skips the tag detection entirely:

$ go build -o matterbox .

A raw go build or go run outside make is always tag-free, so it works on a machine with no cgo, no pkg-config, no ALSA and no FFmpeg. You get matterbox without inline video or demo audio.

Requirements

Another directory

PREFIX moves the install; the binary goes to $PREFIX/bin. Completion and service paths are XDG ones and stay where the shell and the init system look for them.

$ make install PREFIX=~/apps

A release binary by hand

The tarballs are on the releases page — Linux and macOS, amd64 and arm64, with FFmpeg linked in and the Linux ones fully static. Unpack one, check it against the checksums.txt beside it, and drop the binary somewhere on your PATH:

$ sha256sum -c checksums.txt --ignore-missing
$ tar xzf matterbox_linux_amd64.tar.gz
$ install -m 0755 matterbox ~/.local/bin/

Doing it by hand means no completion script, no mmauth:// handler and no service unit. matterbox completion <shell> covers the first — see the CLI page — and matterbox login registers the handler itself on first use.

Optional features

Two features need C libraries, so they sit behind Go build tags. make detects what your machine has and compiles in whatever it can, which is why make install needs no explanation and no flags. You never have to pick.

make tags

What this machine can build, and why it cannot build the rest:

$ make tags

cgo:       yes (CC=gcc)
demoaudio: yes (alsa found)
video:     yes (ffmpeg dev libs found)
tags:      demoaudio,video

Every build prints this block before it starts, so the answer is on screen whether you asked for it or not. A no line names the package that would fix it:

demoaudio: no — ALSA headers not found (Fedora: alsa-lib-devel, …); --demo plays silently
video:     no — ffmpeg dev libs not found (Fedora: ffmpeg-devel, …); video keeps its 🎬 icon

Unlocking the rest

Install the development headers your distribution ships and build again. pkg-config has to be able to find them.

To override the detection rather than satisfy it, name the set yourself. TAGS= with nothing after it turns every optional feature off:

$ make build TAGS=demoaudio
$ make build TAGS=

matterbox --version asks the libraries it actually linked what they are, and prints the build, its optional features and the platform. That is the block worth pasting into a bug report.

Distributing a build

A build of your own is yours to hand out, a tagged one included. matterbox is GPL-3.0-or-later, and the copyleft C code both tags link fits inside that.

One build may not be handed to anyone: an FFmpeg configured --enable-nonfree is not redistributable on any terms. matterbox --version asks the linked library what it is and prints the answer. What travels with a binary is source — whoever you hand one to is entitled to the corresponding source of what you gave them. And:

$ make third-party-licenses

writes the licence bundle for a build. It checks both the Go dependency graph and the linked FFmpeg, and refuses only what cannot be conveyed at all. The long version of all this is docs/building.md in the repository.

PATH and completion

~/.local/bin is on the PATH by default on most distributions, and on none of them reliably. If it is missing, the installer prints the line for your shell rather than writing it:

$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # or ~/.profile
$ fish_add_path ~/.local/bin                              # fish

bash and fish read their completion directories on their own, so the completion script is live in the next shell. zsh needs the directory on its fpath, which is a line in a file of yours — make install appends it, the piped installer prints it:

fpath=(~/.local/share/zsh/site-functions $fpath)
autoload -Uz compinit && compinit

The CLI page has the by-hand form for each shell, PowerShell included, and matterbox completion <shell> --help has the permanent install for it.

The listen service

matterbox listen is the background daemon: it holds a WebSocket open, keeps the message cache warm, and runs your rules. Nothing needs it — the TUI and the CLI work without it — but it is what makes search instant and notifications possible.

make install installs a unit for it and deliberately does not start it, because a daemon that logs in before you have configured anything is just noise. make install-service does that step on its own.

Once you have logged in and configured what you want it to do, turn it on:

$ systemctl --user enable --now matterbox-listen.service   # Linux
$ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.matterbox.listen.plist   # macOS

On older macOS that is launchctl load instead.

First run

Just run it. With no saved login, matterbox opens the first-run wizard by itself — the screen on the landing page — writes the config file and signs you in, then continues into the TUI:

$ matterbox

So there is rarely a reason to name the wizard. matterbox welcome replays it once you are set up — to change an answer, or to point the client at a different server.

Or write ~/.config/matterbox/config.yaml yourself — the only required key is server_url — and log in separately. matterbox login opens your browser for SSO and saves the token; --user signs in with a username or email instead, and --no-browser just prints the URL for a machine with no browser on it:

server_url: https://mattermost.example.com

matterbox rewrites that file on first run with a comment over every key, so the copy on your disk is a filled-in option reference. The configuration page is the long version, and the CLI page has the rest of login's flags.

Upgrading

matterbox replaces itself:

$ matterbox upgrade

How it rebuilds is worked out rather than guessed: a binary with optional features compiled in is rebuilt from source so it keeps them, by running the same installer this page hands out, and one without takes the release binary directly — downloaded, checked against the checksum published with it, and moved into place, without running anything it fetched. matterbox --version prints which of the two you have. It installs next to the binary it is replacing — whatever --dir the original install used, symlinks resolved — so nothing moves on your PATH.

You do not have to remember to run it. matterbox looks for a newer release once a day and then mentions it twice and stops: a small box in the top-right corner, which goes away by itself or when you click it, and a line when you quit, where the command can actually be typed. Nothing is ever installed on its own, and update_check turns the looking off.

Re-running the installer does the same work, and is the route when the binary you have is older than the upgrade command or is not on the PATH to be typed. It prints the version it put in place and, when there was one before, what it replaced:

$ curl -fsSL https://matterbox.work/install.sh | sh

From a clone it is the usual pair. make install re-runs the tag detection, so a build that picks up a library you have installed since needs nothing more than this:

$ git pull
$ make install

To go back to a known-good release, or to hold a machine at one, --version pins every one of the three paths:

$ matterbox upgrade --version v1.0.0
$ curl -fsSL https://matterbox.work/install.sh | sh -s -- --version v1.0.0

Nothing is migrated on upgrade and nothing needs to be: the config file gains keys with their defaults, and the cache is rebuilt from the server as it goes.

Uninstalling

From a clone, one target undoes the whole install — the binary, the completion scripts for all three shells, the mmauth:// handler, and the service, disabled and unloaded before it is removed:

$ make uninstall

It leaves the fpath line in ~/.zshrc alone, because editing your rc file back is not something a Makefile should do unasked. Without a clone, the same thing by hand:

$ rm ~/.local/bin/matterbox
$ rm -f ~/.local/share/zsh/site-functions/_matterbox \
       ~/.local/share/bash-completion/completions/matterbox \
       ~/.config/fish/completions/matterbox.fish
$ rm -rf ~/.local/share/matterbox                         # the licence bundle
$ rm -f ~/.local/share/applications/matterbox-mmauth.desktop