# Install
Install Shelbi with Homebrew on macOS, APT on Ubuntu, or from source for development.
```text
Install and start Shelbi on my machine. On macOS, run `brew install jlong/shelbi/shelbi && shelbi`. On Ubuntu amd64, add the Shelbi APT keyring from https://apt.shelbi.dev/shelbi-archive-keyring.gpg, add the `https://apt.shelbi.dev stable main` source list with signed-by=/etc/apt/keyrings/shelbi-archive-keyring.gpg, then run `sudo apt update && sudo apt install shelbi`, followed by `shelbi`. Make sure tmux 3.2+ and one authenticated agent CLI, claude or codex, are available.
```
On macOS, install Shelbi and start its first-run setup in one command:
```bash
brew install jlong/shelbi/shelbi && shelbi
```
Shelbi checks your prerequisites and current Git checkout before it writes
anything. See [Set up your first project](/docs/guides/getting-started/first-project)
for the one-confirmation flow.
Shelbi also publishes a prebuilt Ubuntu package. The full package-manager
commands are:
```bash
brew install jlong/shelbi/shelbi
```
```bash
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://apt.shelbi.dev/shelbi-archive-keyring.gpg \
| sudo tee /etc/apt/keyrings/shelbi-archive-keyring.gpg >/dev/null
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/shelbi-archive-keyring.gpg] https://apt.shelbi.dev stable main" \
| sudo tee /etc/apt/sources.list.d/shelbi.list >/dev/null
sudo apt update
sudo apt install shelbi
```
The APT repository is signed, so `apt update` verifies the repository
metadata before `apt install` sees the package. The first Ubuntu package is
published for `amd64` in the `stable` suite.
The APT key fingerprint is published at:
```bash
curl -fsSL https://apt.shelbi.dev/shelbi-archive-keyring.fingerprint
```
The package installs the `shelbi` binary only. It does not install or enable
the daemon; run `shelbi daemon install` later if you want the hub daemon managed
by your user service supervisor.
If you're hacking on Shelbi or testing unreleased changes, use the
[source-build path](#install-from-source-for-development) instead.
## Prerequisites
You need three things before you start:
- **`tmux` 3.2 or later.** Shelbi runs every workspace inside a tmux pane
and drives it with `send-keys` / `capture-pane`; older releases miss
features the TUI relies on. Homebrew and APT install this dependency for
the hub, but remote workspace machines need it too.
- **An agent CLI.** At least one of `claude`
([Claude Code](https://docs.claude.com/en/docs/claude-code)) or `codex`,
installed and authenticated. Declare more than one later, and the
project YAML picks per workspace.
- **Git and SSH.** Shelbi creates git worktrees and can run workspaces on
remote machines over SSH. The Ubuntu package depends on `git` and
`openssh-client`; on macOS, install them with Xcode Command Line Tools or
your usual package manager if they are not already present.
Install `tmux` with your package manager:
```bash
brew install tmux
```
```bash
sudo apt install tmux
```
```bash
sudo dnf install tmux
```
Remote workspaces need the same `tmux` and agent CLI on the machine they
run on, plus an `ssh` host you can reach without a password prompt.
## Verify or start later
```bash
shelbi
```
With no project configured, this starts the guided setup. To check only the
installed version, run `shelbi --version`.
## Verify release artifacts manually
GitHub Releases are the source of truth for release artifacts, checksums,
and artifact attestations. Package-manager installs verify checksums or
signed repository metadata automatically, but you can verify downloads by
hand.
For an Ubuntu `.deb`, download the package and `checksums.txt` from the
same release tag:
```bash
version=0.1.0
curl -fsSLO "https://github.com/jlong/shelbi/releases/download/v${version}/checksums.txt"
curl -fsSLO "https://github.com/jlong/shelbi/releases/download/v${version}/shelbi_${version}_amd64.deb"
sha256sum -c checksums.txt --ignore-missing
```
For a macOS archive, verify the release tarball the Homebrew formula uses:
```bash
version=0.1.0
curl -fsSLO "https://github.com/jlong/shelbi/releases/download/v${version}/checksums.txt"
curl -fsSLO "https://github.com/jlong/shelbi/releases/download/v${version}/shelbi_Darwin_arm64.tar.gz"
grep "shelbi_Darwin_arm64.tar.gz" checksums.txt | shasum -a 256 --check -
```
Replace `shelbi_Darwin_arm64.tar.gz` with
`shelbi_Darwin_x86_64.tar.gz` on Intel Macs. To inspect GitHub artifact
attestations, use GitHub's attestation tooling against the same release
artifact.
## Install from source for development
The source install path is for contributors, local patches, and unreleased
builds. It requires the stable Rust toolchain from
[rustup](https://rustup.rs).
You can run the hosted source-build script:
```bash
curl -fsSL https://shelbi.dev/install.sh | sh
```
Or keep the checkout around to rebuild after pulling updates:
```bash
git clone https://github.com/jlong/shelbi.git
cd shelbi
./scripts/install.sh
```
The script runs `cargo build --release` and copies the binary to
`$HOME/bin/shelbi`. Override the destination with `SHELBI_INSTALL_PATH`:
```bash
SHELBI_INSTALL_PATH=/usr/local/bin/shelbi ./scripts/install.sh
```
Re-run it any time you pull updates. One step rebuilds and reinstalls.
The orchestrator and workspace panes re-shell into `shelbi` on every call,
so they pick up the new binary automatically; only the sidebar, Tasks, and
Review views need a manual `shelbi reload` to respawn against the new build.
### macOS: the codesign step
On macOS the script re-signs the copied binary ad-hoc:
```bash
codesign --remove-signature "$INSTALL_PATH"
codesign --sign - "$INSTALL_PATH"
```
`cargo build` embeds an ad-hoc signature; `cp` invalidates it, and the
next exec dies with `Killed: 9` and no useful error. Re-signing after the
copy restores it. `scripts/install.sh` does this for you, so you only hit
the failure if you copy the binary out of `target/release/` by hand.
Linux and Windows don't need it, and the script skips it there.
## Troubleshooting
**`command not found: shelbi`.** The default install path is
`$HOME/bin/shelbi` only when you install from source. Make sure that
directory is on your `PATH`:
```bash
export PATH="$HOME/bin:$PATH"
```
```zsh
export PATH="$HOME/bin:$PATH"
```
```fish
fish_add_path "$HOME/bin"
```
Add the line to `~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish` to
make it persistent. Or pass
`SHELBI_INSTALL_PATH=/usr/local/bin/shelbi` to the install script so the
binary lands somewhere already on your `PATH`.
If Homebrew or APT installed the package, open a new shell and run
`which shelbi` to confirm your package-manager binary directory is on
`PATH`.
**`Killed: 9` on macOS, no other output.** The codesign step didn't run.
This usually means you copied the binary out of `target/release/` by hand
instead of using `scripts/install.sh`. Re-run the script, or run the
codesign commands yourself against your install path.
**`cargo: command not found`.** Install Rust via
[rustup](https://rustup.rs) and restart your shell so `~/.cargo/bin` is on
your `PATH`. Cargo is only required for source builds.
**`tmux: command not found`** (or `tmux 1.x` warnings). Install or
upgrade tmux to 3.2+. The TUI assumes modern pane title and popup
support; older versions render incorrectly.
## Next
You have the binary. Now point it at a repo with
[Set up your first project](/docs/guides/getting-started/first-project).