# Install (/docs/rlx/install)

One line sets up everything the fleet needs and skips whatever you already
have. If you would rather see each step, installing by hand with uv is fully
supported, and memory alone needs nothing but uv and Claude Code.

These pages document **release 0.10.1**. `rlx --version` prints the
release you have (`aisquare --version` on a release from before rlx).

## The one-line installer [#the-one-line-installer]

```sh
curl -fsSL https://aisquare.studio/rlx/install.sh | sh
```

For Codex too, end the line with `| sh -s -- --agent both` instead of `| sh`
(`| sh -s -- --agent codex` for Codex alone).

It runs on macOS, Linux and WSL2. It works out what your machine already has
and installs only what is missing: [uv](https://docs.astral.sh/uv/), a Python
3.13 used by rlx alone, the `aisquare-cli` package, tmux, gh, git and
[Claude Code](https://claude.com/claude-code). It then offers browser tools for
the ui-tester (Node and the Chrome DevTools MCP), with a prompt that defaults
to no, registers the git repo you ran it from as your first project, wires
Claude Code's hooks, and offers to open the UI.

Running it again is a no-op: it reports what is current and installs nothing.

It refuses to run as root outside a container, uses `sudo` only for the system
packages (one command at a time), and never edits your shell profile beyond
what uv and the Claude Code installer do themselves.

### Which installer runs [#which-installer-runs]

The one-line installer's short URL, `https://aisquare.studio/rlx/install.sh`,
points at the copy on `main`. That copy hands off to the latest release's own
`install.sh`, checks it, and runs it, saying `using the v0.10.1 installer`, so
the steps and checks are always the ones that release was tested with. If it
cannot download or check that copy, it says why and runs itself.
`--no-handoff` keeps `main`'s copy.

### Pin a release [#pin-a-release]

Every release from 0.9.0 on carries its own `install.sh` and `install.ps1`,
which install exactly that version. Replace `vX.Y.Z` with the release's tag;
the `rlx` command arrives with 0.10.1, so pin 0.10.1 or later for the commands
on these pages:

```sh
curl -fsSL https://github.com/AISquare-Studio/rlx/releases/download/vX.Y.Z/install.sh | sh
```

`--version V` still overrides a script's own version, and `--version latest`
drops the pin. A pinned install still gets the update offer; taking it, or
running `rlx upgrade`, moves to the newest release and drops the pin.

### Read it before you run it [#read-it-before-you-run-it]

Piping a script into a shell deserves a look first. This downloads it, shows
it, and prints every command it would run without running any:

```sh
curl -fsSL https://aisquare.studio/rlx/install.sh -o install.sh
less install.sh
sh install.sh --dry-run
```

To pass flags while piping, add `-s --`, since `sh` is reading the script on
stdin: `curl -fsSL https://aisquare.studio/rlx/install.sh | sh -s -- --yes --no-agent`.

| Flag                     | What it does                                                                                                                                                    |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--yes`                  | Never prompt, and do not open the UI at the end. For CI and Dockerfiles. Optional extras install only when named with `--with`.                                 |
| `--dry-run`              | Print every command, run none.                                                                                                                                  |
| `--agent NAME`           | The coding agent to install and connect: `claude-code` (the default), `codex`, or `both`. Repeat it to name both.                                               |
| `--no-agent`             | Skip installing and connecting any coding agent, and its hooks.                                                                                                 |
| `--no-system-deps`       | Skip tmux, gh and git, and ask about no optional extra.                                                                                                         |
| `--with chrome-devtools` | Install Node 22.12+ and register the Chrome DevTools MCP with Claude Code at user scope, without asking. `claude mcp remove -s user chrome-devtools` undoes it. |
| `--project DIR`          | Register `DIR` instead of the current directory.                                                                                                                |
| `--no-project`           | Set up the machine, register nothing.                                                                                                                           |
| `--version V`            | Pin `aisquare-cli` to `V`, or `latest`.                                                                                                                         |
| `--python V`             | The Python uv resolves for rlx (default 3.13).                                                                                                                  |
| `--offline`              | Do not ask PyPI for the latest version, and do not hand off.                                                                                                    |
| `--no-handoff`           | Run this copy of the script, not the release's own.                                                                                                             |
| `--upgrade-all`          | Also move uv itself and the system packages.                                                                                                                    |
| `--force`                | Reinstall `aisquare-cli` even when the version matches.                                                                                                         |

It exits `0` when everything installed, `1` when a required step (uv, or
`aisquare-cli` itself) failed, and `2` when it installed but a check is amber
for a reason it did not expect, or an optional extra you chose did not install.

## Windows: through WSL2 [#windows-through-wsl2]

The fleet gives every agent a real tmux pane, and Windows has no tmux, so on
Windows the fleet runs inside WSL2. This PowerShell line runs the installer
inside your WSL2 distribution or, when there is none, prints the one command
that installs WSL2:

```text
irm https://aisquare.studio/rlx/install.ps1 | iex
```

## Install by hand with uv [#install-by-hand-with-uv]

The package is `aisquare-cli`, and its command is `rlx`.

```sh
UV_PYTHON_DOWNLOADS=automatic uv tool install --python 3.13 aisquare-cli
cd path/to/your/repo
rlx init --local --yes --agent claude-code
```

`pipx install aisquare-cli` works too. `init` registers the repo you run it in
and installs Claude Code's hooks, which are how the UI and the board learn what
each session is doing. Run `rlx agents connect claude-code` later if you
skipped it.

The fleet also needs tmux, which is a system package:

```sh
sudo apt install tmux        # Debian / Ubuntu
sudo dnf install tmux        # Fedora / RHEL
brew install tmux            # macOS
tmux -V                      # 3.2 or newer
```

### Optional extras [#optional-extras]

Everything the fleet, the board, memory and Remote need is in the core
package. A few features take an extra, named in brackets, such as
`uv tool install --python 3.13 'aisquare-cli[serve,code]'`:

| Extra   | For                                                                                    |
| ------- | -------------------------------------------------------------------------------------- |
| `serve` | `rlx serve`, the board as an MCP server. See [Remote agents](/docs/rlx/remote-agents). |
| `code`  | The symbol index for TypeScript and JavaScript. Python needs nothing.                  |
| `llm`   | Persona import through the Anthropic API. See [Personas](/docs/rlx/personas).          |

uv cannot add a package to an installed tool, so installing with an extra
installs the tool again and keeps only what that line names: list every extra
you use. `rlx upgrade` keeps the extras an install already has.

## Or as a Claude Code plugin [#or-as-a-claude-code-plugin]

If you only want memory and would rather install nothing outside Claude Code,
the rlx plugin gives Claude Code the same hooks. Inside Claude Code:

```text
/plugin marketplace add AISquare-Studio/rlx
/plugin install aisquare@aisquare-cli
```

Then start a new session (or run `/reload-plugins` if Claude Code asks). The
hooks run your installed rlx when there is one, and otherwise the release
the plugin pins, through `uvx`. A hook that fails never blocks a prompt or a
session.

Keep one route. If you also ran the installer or `rlx agents connect
claude-code`, the plugin's hooks stand down so nothing fires twice, and
`rlx doctor` warns until you remove one. The fleet's extra Claude accounts
keep their own `settings.json` hooks either way. Claude Code does not update
third-party plugins by default; after an rlx release run
`claude plugin marketplace update aisquare-cli`, then
`claude plugin update aisquare@aisquare-cli`.

## Requirements [#requirements]

| Tool                                                   | Needed for                                                                                              | Minimum                                                                                   |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| macOS, Linux or WSL2                                   | the fleet                                                                                               |                                                                                           |
| [Claude Code](https://claude.com/claude-code) or Codex | the agents, either or both                                                                              | Claude Code: a current release. Codex: 0.164.0                                            |
| tmux                                                   | running and showing agents                                                                              | 3.2 (3.5 or newer recommended: there shift+enter and other extended keys reach the agent) |
| git                                                    | a worktree for each coder and reviewer                                                                  |                                                                                           |
| gh                                                     | optional: coders open pull requests and reviewers review them with it                                   | any current release                                                                       |
| Python                                                 | rlx, if you install by hand (the one-liner brings its own 3.13)                                         | 3.11                                                                                      |
| Node                                                   | optional: browser tools for the ui-tester, such as the Chrome DevTools MCP. rlx itself never runs Node. | 22.12                                                                                     |

## Check the machine [#check-the-machine]

```sh
rlx doctor            # this machine and the project you are in
rlx doctor --live     # also the checks that leave the machine
rlx doctor --fix      # create a missing ~/.aisquare, then check again
```

Doctor checks every dependency and prints the exact command that fixes
anything missing. Inside `rlx&#x60; the same report is under **⚙ Settings ▸
Doctor**, where a known fix is one click. See
[Reference](/docs/rlx/reference#doctor) for what it checks.

## Update [#update]

`rlx&#x60; asks PyPI at most once a day whether a newer release is out. When one
is, a row under **⚙ Settings** in the sidebar says so, such as
`⬆ 0.10.2 · restart to update`. Click it: the dialog counts your live agents,
and **Restart & update** closes `rlx`, runs `rlx upgrade`, and reopens
`rlx` on the new version in the view you had open. The agents live on the
fleet's own tmux server, so the update does not touch them; any whose pane is
gone after the reopen is restarted on its session, and a toast says what it
found. If the install fails, its output stays on screen and the version you had
reopens. A Homebrew, pip or pipx install reads `· how to update` instead, and
the dialog says to update it the way you installed it.

From a shell:

```sh
rlx upgrade                   # install the latest release in place
rlx upgrade --check           # only say whether a newer release exists
rlx upgrade --version 0.10.1  # move to a given release, older included
```

On a release from before rlx, which has no `rlx` command yet, run the same
commands as `aisquare upgrade`, or use the `⬆` row.

`upgrade` keeps your install's extras and reconnects Claude Code's hooks in
every Claude Code directory the machine connected. It runs on the uv tool
install the one-liner makes; any other install is told the command that
updates it. It asks first at a terminal, and off a terminal it is a dry run
unless you pass `--yes`. A source checkout or an editable install is never
offered an update.

Turn the daily check off with **App settings ▸ User preferences ▸ Check for a
new release daily**, or `rlx config set updates.check false`.

### Upgrading from 0.10.0 [#upgrading-from-0100]

0.10.1 adds the `rlx` and `relax` commands to `~/.local/bin`. If another
program's `rlx` or `relax` is already there (PyPI's `relax` is another
project), 0.10.0's `aisquare upgrade`, its *Update* and
`uv tool upgrade aisquare-cli` replace it without asking. Move yours aside
first, or update with the one-line installer, which stops and names the file.
From 0.10.1 on, `rlx upgrade`, the app's *Update* and `rlx uninstall` stop the
same way.

### Upgrading from 0.8.x [#upgrading-from-08x]

The update offer starts with 0.9.0, so from 0.8.x run `aisquare upgrade`
once by hand. From 0.7.0 or earlier, re-run the one-line installer. The store
and the config file migrate themselves on first open, and moving back with
`rlx upgrade --version` is safe. What you will notice:

* **A spawn runs the model and effort you last chose.** Your last `/model` and
  `/effort` in any fleet agent are remembered and reused; with no choice made,
  Claude Code runs the account's own default. See
  [Run a fleet](/docs/rlx/fleet).
* **Rank 1 is the machine default account.** There is no separate default.
  With nothing more specific, a launch still goes to the first account in your
  order that is under the usage line (`accounts.pick = headroom`, the
  default); rank 1, the first enabled, signed-in account, decides under
  `pick = default` or when no usage can be read. A role bound by hand with
  `team bind <role> --env CLAUDE_CONFIG_DIR=…` launches on its own directory.
  See [Accounts and usage](/docs/rlx/accounts).
* **The codebase snapshot and the project brain are gone.** rlx no longer
  packs your codebase or needs Node, and `aisquare recall`,
  `aisquare team distill` and the `recall` MCP tool are removed. An existing
  `~/.aisquare/projects/<id>/brain` stays on disk. A symbol index,
  `rlx code`, answers where code is defined and used.
* **Tracing is parked.** Explainability is out of `rlx doctor` and out of
  every screen, and runs only through its own commands. See
  [Tracing (parked)](/docs/rlx/explainability).
* **Remote needs nothing more installed.** The `remote` extra still resolves
  and adds nothing.
* **Usage & stats reads every Claude Code transcript on this machine**, under
  `~/.claude` and every account you added, whether or not rlx launched the
  session. The figures stay on the machine; nothing is sent unless you turn
  sharing on. See [See where your usage goes](/docs/rlx/usage-and-stats).
* **A reviewer's file-edit deny belongs to the role now.** A reviewer whose
  `extra_args` were exactly 0.8.2's default loses them once, and keeps the
  same deny.
* **On a shared machine**, an agent's first message rides on its command line,
  where other local users can read it in `ps` while the agent runs.
  `rlx config set fleet.first_prompt type` keeps it off the command line.
* **A task title with letters outside ASCII gets a new key**, so re-adding
  such a title can add a task beside one added before the upgrade. Every ASCII
  title keys as before.

The [0.9.0](https://github.com/AISquare-Studio/rlx/releases/tag/v0.9.0)
and [0.9.1](https://github.com/AISquare-Studio/rlx/releases/tag/v0.9.1)
release notes list every change.

## Uninstall [#uninstall]

```sh
rlx uninstall --dry-run   # show what it would remove, remove nothing
rlx uninstall             # remove the hooks and the package
rlx uninstall --purge     # also delete ~/.aisquare (memory, boards, account slots)
```

`uninstall` takes rlx's hooks, and its Claude Code status line if you
installed one, out of every Claude Code directory it finds, leaving every
other hook as it was. Then it removes the package of a uv tool install; for any
other install it prints the command that removes it. It shows its plan and
asks first, and refuses while fleet agents are running. Your memory, boards and
settings in `~/.aisquare` stay unless you add `--purge`, which also removes the
Claude account slots you added (on macOS their sign-in tokens stay in the
Keychain). The Claude Code plugin belongs to Claude Code, so `uninstall` names
the command that removes it rather than removing it itself, and `--purge`
waits until you have: it refuses while the plugin is enabled.

## Next [#next]

<Cards>
  <Card title="Quickstart" href="/docs/rlx/quickstart" description="Open rlx and get a manager and two coders working on your goal." />

  <Card title="Tour of rlx" href="/docs/rlx/fleet-ui" description="The sidebar, agent panes, Settings and the keys you will use every day." />
</Cards>
