Installation

RimZ is a single binary for macOS and Linux. Pick one host install path: the install script, Homebrew on macOS, a prebuilt binary from the releases page, or Cargo. Run in Docker for a self-contained room with the supported tools already installed. Building from source is for working on RimZ itself or for platforms the prebuilt paths miss.

Prerequisites

• macOS or Linux.
• A terminal multiplexer — Zellij 0.44 or newer, or tmux 3.5 or newer. One is enough; both are first-class. Distribution packages are often too old; get a current Zellij or tmux has install recipes for current builds.
• The agent CLIs you plan to run on a host install — Claude Code, Codex, Pi, OpenCode, Droid, Kiro CLI, or Grok Build, installed per their own docs. RimZ drives the stock CLIs; the Docker image preinstalls Claude Code, Codex, Pi, and OpenCode.
• Git — agent worktrees and the sidebar's git status use it.

RimZ refuses to start against a multiplexer below the minimum supported version, and rimz doctor reports the installed version and whether it clears that floor. On tmux, 3.6 or newer gives the best experience (why).

The multiplexer needs no configuration for RimZ: every room sets its own options on session start and reattach, and your existing Zellij or tmux config keeps owning your theme, shell, and keybinds. The room's essential settings are in set up your machine, and a full baseline for your own sessions is Zellij and tmux baselines.

Run in Docker

A normal container gives a clean shell but leaves you to assemble its developer tools. The RimZ image starts as uid 1000 with RimZ, current Zellij, tmux, ttyd, GitHub CLI, Node.js, Claude Code, Codex, Pi, and OpenCode ready on PATH:

docker run --rm -it -v "$PWD":/workspace ghcr.io/rimio-ai/rimz

The bind mount makes the current checkout the room at /workspace. Agent authentication otherwise disappears with the container; add a named home volume to keep logins, agent state, RimZ configuration, and the hooks baked into the image:

docker run --rm -it \
  -v "$PWD":/workspace \
  -v rimz-home:/home/rimz \
  ghcr.io/rimio-ai/rimz

Codex keeps per-hook trust behind its own UI, so the image leaves that consent to you: after the first Codex launch, run /hooks inside Codex and trust the RimZ hooks. rimz doctor reports the hooks as installed but untrusted until then.

The web command births the /workspace room, binds RimZ to every container interface, and leaves the authenticated ttyd daemon online:

docker run -d --name rimz-web \
  -p 8200:8200 \
  -v "$PWD":/workspace \
  -v rimz-home:/home/rimz \
  ghcr.io/rimio-ai/rimz web
docker logs rimz-web              # URL and generated Basic credential
docker rm -f rimz-web             # stop and remove it

The default and debian tags use Debian 13; ubuntu uses Ubuntu 26.04 LTS. A release such as 0.4.2 also has 0.4.2-debian and 0.4.2-ubuntu tags. The workflow refreshes these tags daily so the bundled toolchain stays current; pin an image digest when the complete filesystem must stay immutable.

The uid-1000 rimz user has passwordless sudo, so the same image works as a devcontainer base:

{
  "image": "ghcr.io/rimio-ai/rimz",
  "remoteUser": "rimz"
}

Docker builds run on both amd64 and arm64. Use the normal host install when you need another agent CLI, direct access to an existing host multiplexer, or native desktop integration.

Install with the script

curl -fsSL https://raw.githubusercontent.com/rimio-ai/rimz/main/scripts/install.sh | sh

The script detects the platform. On macOS, a latest-release install delegates to the Homebrew tap when brew is available, which puts RimZ on the same package-manager path as future upgrades and removal. A RIMZ_VERSION other than latest, RIMZ_INSTALL_DIR, an existing non-Homebrew rimz on PATH, or RIMZ_NO_BREW=1 keeps the direct-download path; a failed Homebrew install also falls back to the release download.

The direct path downloads the release, verifies it against SHA256SUMS, and installs RimZ to /usr/local/bin when that directory is writable or ~/.local/bin otherwise. Interactive terminals show a short control-room boot animation; non-interactive terminals, redirected output, NO_COLOR, and TERM=dumb use the same plain progress output.

Pass RIMZ_INSTALL_DIR or RIMZ_VERSION to the sh command on the right side of the pipe to choose the destination or install a specific tag such as v0.3 or the rolling latest-main build. Unsupported prebuilt platforms, including ARM Linux and musl Linux, are directed to the Cargo install.

Install with Homebrew (macOS)

brew install rimio-ai/rimz/rimz

Homebrew adds the rimio-ai/rimz tap automatically. Run rimz update to refresh formula data and upgrade rimio-ai/rimz/rimz. The install script reaches this path automatically on macOS when its Homebrew delegation conditions hold.

Install a prebuilt binary

Every release ships one archive per platform plus a SHA256SUMS file:

Download, verify, and install (shown for Linux; swap the archive name on macOS and verify with shasum -a 256 -c --ignore-missing):

curl -fsSLO https://github.com/rimio-ai/rimz/releases/latest/download/rimz-x86_64-unknown-linux-gnu.tar.gz
curl -fsSLO https://github.com/rimio-ai/rimz/releases/latest/download/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
tar -xzf rimz-x86_64-unknown-linux-gnu.tar.gz
sudo install -m 0755 rimz-x86_64-unknown-linux-gnu/rimz /usr/local/bin/rimz

Three notes on the archives:

• The Linux binary targets x86_64 and links against a current glibc. On an ARM Linux machine, or if the binary reports a GLIBC version error, use the Cargo install instead.
• The macOS binaries carry an ad-hoc signature and install cleanly over curl. A browser download gets quarantined by Gatekeeper; xattr -d com.apple.quarantine rimz clears it.
• The latest-main prerelease carries a rolling build of the default branch, for when you want a fix that has not been tagged yet.

Install with Cargo

cargo install --locked rimz

This builds RimZ from crates.io and works on any supported platform, including ARM Linux. It needs the Rust toolchain (install through rustup) and a C linker (build-essential on Debian/Ubuntu, xcode-select --install on macOS). The crate ships RimZ's Zellij plugin as a prebuilt WebAssembly artifact, so no extra Rust targets are involved.

Verify the install

rimz --version
rimz doctor

rimz doctor reports the multiplexer it selected, its version and whether it clears the floor, hook status, and room health — the fastest read on whether a fresh machine is ready. From here, make the machine comfortable with set up your machine.

Update

Whichever install path you chose, update it from the same command:

rimz update

rimz update detects the current binary's install path. A Homebrew install, including a macOS script install that delegated to Homebrew, refreshes formula data with brew update and then runs brew upgrade rimio-ai/rimz/rimz, so stale tap data cannot skip a released build; a Cargo install runs cargo install --locked rimz. Direct-download script and manually installed prebuilt binaries download the matching release archive, verify it against SHA256SUMS, extract only the RimZ binary, require its --version smoke test to pass, then atomically replace the current binary in place. When the binary changes, the new build runs rimz reload so live sidebars and held stats dashboards converge immediately.

Pass --version <TAG> to install a standalone release such as v0.3.1, roll back to an older tag, or follow the rolling latest-main build. Cargo accepts numbered release tags and normalizes short tags such as v0.3 to 0.3.0; crates.io has no latest-main build. Homebrew owns its selected formula version, so pin a standalone install through the install script instead.

Get a current Zellij or tmux

A distribution's packaged tmux is usually behind (Debian 12 ships 3.3a, Debian 13 ships 3.5a), and most distributions do not package Zellij at all. When tmux -V or zellij --version reads below the floor, install a current build.

On macOS, Homebrew's builds of both are current:

brew install zellij
brew install tmux         # one is enough; keep both to choose per project

On Linux, Zellij ships a prebuilt binary on its releases page; drop it into your PATH (swap x86_64 for aarch64 on ARM):

curl -L https://github.com/zellij-org/zellij/releases/latest/download/zellij-x86_64-unknown-linux-musl.tar.gz \
  | sudo tar -xz -C /usr/local/bin zellij
zellij --version

For tmux, the distribution package works when tmux -V clears the version you want:

sudo apt install tmux     # Debian/Ubuntu; dnf and pacman ship it too

tmux publishes no prebuilt binaries, so when the packaged one is too old, install a current one through Homebrew on Linux or build the release tarball (the first line installs the build deps):

sudo apt install -y build-essential pkg-config libevent-dev libncurses-dev bison
curl -fsSLO https://github.com/tmux/tmux/releases/download/3.7/tmux-3.7.tar.gz
tar -xzf tmux-3.7.tar.gz && cd tmux-3.7
./configure && make -j"$(nproc)" && sudo make install

Truecolor terminal and a Nerd Font (optional)

RimZ's modern style paints in 24-bit color and draws with Nerd Font icons. First-run setup checks the color sweep and icon sample separately, so truecolor and Nerd Font glyphs can be enabled independently; plain indexed colors and Unicode glyphs read at any depth. Truecolor is on by default in Ghostty, kitty, WezTerm, iTerm2, and Alacritty; the icons need a Nerd Font installed and selected as your terminal font.

Ghostty and kitty get you the fullest experience: they also draw crisp pixel pets through the kitty graphics protocol, where every other terminal falls back to the portable cell-art tier. For truecolor, Nerd Font icons, and pixel pets in one terminal, pick one of these two.

On macOS, Homebrew installs Ghostty and a couple of patched fonts in one step:

brew install --cask ghostty
brew install --cask font-cascadia-code-nf font-jetbrains-maple-mono-nf

Set the installed font as your terminal font, then rerun rimz setup to enable Nerd Font icons. The theming guide has the color-depth and glyph knobs, and the pets guide covers the pixel and cell-art tiers.

Build from source

The source build is for contributing to RimZ or installing on a platform the prebuilt paths miss. Beyond the prerequisites above it needs a C toolchain, Git, and Rust through rustup:

# Linux — build tools (Debian/Ubuntu shown; use dnf or pacman equivalents)
sudo apt install -y build-essential pkg-config git

# macOS — Apple's command-line tools
xcode-select --install

# Both — Rust through rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"

Then clone and install:

git clone https://github.com/rimio-ai/rimz.git
cd rimz
cargo xtask install

cargo xtask install builds the Zellij presence plugin (a WebAssembly artifact embedded into the binary), builds rimz, copies it into ~/.cargo/bin, and prints the installed version and path. The repo's rust-toolchain.toml pins the toolchain channel, components, and the wasm32-wasip1 target, and rustup applies it on the first build — there is no manual target setup.

To work on RimZ itself (debug builds, tests, the gate stack), continue with the Rust conventions.

Uninstall

Run rimz uninstall --all from outside a RimZ room. It removes installed hooks, live rooms, runtime state, durable stores, per-machine config, and the installed binary; project-local .rimz/ dirs and RimZ-owned worktrees stay in place for manual review. If you installed through Homebrew, also run brew uninstall rimz. Flags for partial removal are in the maintenance reference.

Troubleshooting

rimz doctor flags the multiplexer as unsupported

RimZ refuses to start against a multiplexer too old to carry the room options it sets: tmux below 3.5, or Zellij below 0.44. Check the installed version, then install a current build.

tmux -V
zellij --version
rimz doctor

One tmux nuance: on tmux 3.5.x the extended keys RimZ enables (so Shift+Enter and Alt+Enter reach agents as soft newlines) corrupt pasted multiline text; tmux 3.6 fixes the paste too.

GLIBC_x.xx not found running the prebuilt Linux binary

The release binary links against a current glibc, and an older distribution cannot load it. Install through Cargo instead, which builds against your system's glibc.

can't find crate for core during a source build

This error during cargo xtask install means the compiler Cargo used cannot see the Rust standard library for wasm32-wasip1:

error[E0463]: can't find crate for `core`
  = note: the `wasm32-wasip1` target may not be installed

The usual cause is a non-rustup Rust shadowing rustup's on your PATH — on macOS, Homebrew's rust formula is the common culprit. Check where the tools resolve:

command -v cargo
command -v rustc
rustup show active-toolchain

A healthy setup resolves both under $HOME/.cargo/bin (or rustup's own bin directory). If they point elsewhere, put rustup first and remove the shadowing toolchain, then rerun cargo xtask install:

brew unlink rust        # macOS, if Homebrew's rust formula is installed
hash -r