> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rakumux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install, update and remove Rakumux on macOS and Linux.

Native binaries are available for **macOS Apple Silicon**, **macOS Intel** and **Linux x64**.
The installed app needs no git, tmux, jq or Python: only bash, and Node.js when installed with npm.
Install it on a remote machine as well as, or instead of, your laptop: see
[Where to run Rakumux](https://docs.rakumux.com/remote.md).

```bash curl theme={null}
curl -fsSL https://rakumux.com/install.sh | bash
```

```bash npm theme={null}
npm install -g rakumux
```

| | curl | npm |
| - | - | - |
| Needs | bash | Node.js, which also starts the commands |
| Downloads | your system's package (16–18 MB) | every system's binaries (about 50 MB) |
| Updates | `U` in Rakumux | `U` in Rakumux, through npm |

## Installer

The installer picks the package for your system, downloads it from the
[GitHub release](https://github.com/humanunsupervised/rakumux/releases), checks it against the
release's `checksums.txt`, and runs the package's own installer. It installs into `/usr/local` and
asks for `sudo` only when it needs to.

> [tab] User-local
>
> Install into your home directory instead, which also lets Rakumux update itself without
> `sudo`:
>
> ```bash theme={null}
> curl -fsSL https://rakumux.com/install.sh | PREFIX="$HOME/.local" bash
> ```

> [tab] A specific version
>
> ```bash theme={null}
> curl -fsSL https://rakumux.com/install.sh | RAKUMUX_VERSION=0.1.9 bash
> ```

The package goes in `$PREFIX/libexec/rakumux`, and four commands go in `$PREFIX/bin`:

| Command | What it is |
| - | - |
| `rakumux` | The terminal UI and the command line |
| `rakumux-mcp` | The MCP server for coding agents ([MCP server](https://docs.rakumux.com/agents/mcp.md)) |
| `rakumux-api` | The local HTTP API, started on demand ([API reference](https://docs.rakumux.com/api-reference/introduction.md)) |
| `rakumux-local` | Runs a source checkout of Rakumux |

The background server, `rakumux-ptyd`, ships in the package and starts by itself when needed.

## npm

The package carries the binaries for all three systems and sets up the one for yours, with the
same four commands in npm's global `bin`.

## Release tarball

Download a package from [GitHub Releases](https://github.com/humanunsupervised/rakumux/releases)
and run its installer:

```bash theme={null}
curl -fL https://github.com/humanunsupervised/rakumux/releases/latest/download/rakumux-linux-x64.tar.gz | tar xz
cd rakumux-linux-x64
./install.sh                          # /usr/local (asks for sudo if needed)
PREFIX="$HOME/.local" ./install.sh    # or any other prefix
```

The packages are `rakumux-linux-x64.tar.gz`, `rakumux-macos-arm64.tar.gz` and
`rakumux-macos-intel.tar.gz`.

## From source

You need a stable Rust toolchain, a C compiler and bash. SQLite is bundled.

```bash theme={null}
git clone https://github.com/humanunsupervised/rakumux.git
cd rakumux
./build.sh       # builds the UI, the server, the API and the MCP server
./rakumux.sh     # run from the checkout
```

`./build.sh --install` also installs the binaries into `~/.cargo/bin`.

## Updating

Press `Shift+U` in Rakumux mode (`Ctrl-\` first if you're working in a session), or open
**Settings → Update**. Rakumux checks for a new release, and `Enter` confirms the installation.
It downloads the release, verifies its SHA-256 checksum and version, swaps the installed files
in one step, and restarts **only the UI**. The background server and every running session stay
up.

* **Needs a writable install.** Automatic updates need write access to the install directory. A
  user-local install (`PREFIX="$HOME/.local"`) normally has it. For an install in `/usr/local`,
  re-run the installer with the same `PREFIX`; Rakumux never asks for `sudo` behind your back.
* **npm installs** update through npm: `U` checks npm for the latest version, runs
  `npm install -g rakumux@<version>` and restarts only the UI. If npm needs administrator rights
  for that, `U` says so: run `npm install -g rakumux@latest` yourself, as you installed it.
* **Source builds** are never overwritten: rebuild with `./build.sh`, then press `R` to reload the
  UI.
* **The server** isn't restarted by an update. To run the new server, restart it in place with
  `S` in Rakumux mode, **Settings → Restart server** or `rakumux daemon restart`: sessions and
  their programs keep running.

You can also update by re-running the installer, or with `npm install -g rakumux@latest`.

## Uninstall

```bash theme={null}
sudo rm -rf /usr/local/libexec/rakumux \
  /usr/local/bin/rakumux /usr/local/bin/rakumux-local \
  /usr/local/bin/rakumux-mcp /usr/local/bin/rakumux-api
```

Use your `PREFIX` in place of `/usr/local` if you installed elsewhere (and drop `sudo` for a
user-local install). Installed with npm: `npm uninstall -g rakumux`. Your sessions and settings
live in `~/.rakumux`; remove it to start fresh.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.