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

# Install o4

> Install o4 on macOS or Linux with the install script, Homebrew, or a release archive.

o4 is one executable file. Install it with the install script, with Homebrew,
or by downloading a release archive yourself. All three methods install the
same binary from the
[o4 releases page](https://github.com/Open4rena/o4-releases/releases).

## Supported platforms

| Operating system | Architecture | Release archive |
| - | - | - |
| macOS | Apple silicon (arm64) | `o4-macos-arm64.tar.gz` |
| Linux | arm64 (aarch64) | `o4-linux-arm64.tar.gz` |
| Linux | x86\_64 | `o4-linux-x86_64.tar.gz` |

The Linux binaries are statically linked, so they don't depend on your
distribution's C library. There is no Windows build, and no build for Intel
Macs: the last release with one, `o4-macos-x86_64.tar.gz`, is 0.2.54. On an
Intel Mac, the install script stops at the download step with
`download failed — does version <version> exist for macos/x86_64?`, and
Homebrew won't install o4. To install 0.2.54 there, run the install script
with `O4_VERSION=0.2.54`.

## Install

<Tabs>
  <Tab title="Install script">
    Run:

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

    The script:

    1. Checks that `curl`, `tar`, and `sha256sum` or `shasum` are installed.
    2. Detects your operating system and architecture, and stops with an error
       on anything other than macOS or Linux on x86\_64 or arm64.
    3. Looks up the latest release, unless you set `O4_VERSION`.
    4. Downloads the archive for your platform and its `.sha256` checksum file.
    5. Checks the archive against the checksum and stops if they don't match.
    6. Installs the binary as `o4` in `~/.local/bin`, creating the folder if
       needed. An existing `o4` in that folder is replaced.
    7. Tells you if the install folder isn't on your `PATH` (see
       [Add o4 to your PATH](#add-o4-to-your-path)).

    Two environment variables change what the script does:

    | Variable | Effect |
    | - | - |
    | `O4_INSTALL_DIR` | Install into this folder instead of `~/.local/bin`. |
    | `O4_VERSION` | Install this version instead of the latest, for example `0.2.54`. |

    Set them on the `bash` side of the pipe, so the script sees them:

    ```bash theme={null}
    curl -fsSL https://open4rena.ai/install.sh | O4_INSTALL_DIR="$HOME/bin" O4_VERSION=0.2.54 bash
    ```
  </Tab>

  <Tab title="Homebrew">
    Run:

    ```bash theme={null}
    brew install open4rena/tap/o4
    ```

    The formula is in the `open4rena/tap` tap. It works on Apple silicon Macs
    and on Linux, picks the archive for your platform, and installs `o4` into
    Homebrew's `bin` folder.
  </Tab>

  <Tab title="Release archive">
    Download the archive for your platform and its checksum file. This example
    uses Apple silicon; replace `o4-macos-arm64` with the name for your
    platform from the table above.

    ```bash theme={null}
    curl -fsSLO https://github.com/Open4rena/o4-releases/releases/latest/download/o4-macos-arm64.tar.gz
    curl -fsSLO https://github.com/Open4rena/o4-releases/releases/latest/download/o4-macos-arm64.tar.gz.sha256
    ```

    Check the archive against the checksum. On macOS:

    ```bash theme={null}
    shasum -a 256 -c o4-macos-arm64.tar.gz.sha256
    ```

    On Linux:

    ```bash theme={null}
    sha256sum -c o4-linux-x86_64.tar.gz.sha256
    ```

    The command prints `OK` after the file name when the archive is intact.
    Don't install an archive that fails this check.

    Each archive holds one file named after the platform. Extract it and
    install it as `o4`:

    ```bash theme={null}
    tar -xzf o4-macos-arm64.tar.gz
    mkdir -p ~/.local/bin
    install -m 755 o4-macos-arm64 ~/.local/bin/o4
    ```

    To install an older version, replace `latest/download` in the URLs with
    `download/v` followed by the version, for example `download/v0.2.54`.
  </Tab>
</Tabs>

## Add o4 to your PATH

The install script and the manual steps put `o4` in `~/.local/bin`. If that
folder isn't on your `PATH`, the script prints a note and the command to fix
it, for example:

```text theme={null}
> NOTE: /Users/you/.local/bin is not in your PATH.

  Add it to your shell profile:

    echo 'export PATH="/Users/you/.local/bin:$PATH"' >> ~/.zshrc
```

The script suggests `~/.zshrc` if you have one, then `~/.bashrc`. If you have
neither, it prints only the `export` line; add that line to your shell's
startup file. Run the suggested command, then open a new terminal. For zsh,
that's:

```bash theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
```

For bash, use `~/.bashrc` instead of `~/.zshrc`. Homebrew installs don't need
this step.

## Check the install

```bash theme={null}
o4 --version
```

This prints the version you installed:

```text theme={null}
o4 0.2.74
```

If your shell says `command not found`, the install folder isn't on your
`PATH` yet. If you installed o4 more than one way, run `which -a o4` to see
every copy on your `PATH`; the first one listed is the one that runs.

Next, follow the [Quickstart](/quickstart) to connect a model and run your
first task.

## Update o4

Run `o4 update`. It downloads the latest release, checks it against the
published checksum, and replaces the binary you ran:

```bash theme={null}
o4 update
```

`o4 update --check` only reports whether a newer release exists, and
`o4 update --version 0.2.67` installs that release, even if it's older. Without
`--version`, o4 never replaces a build that is newer than the latest release.
If o4 was installed with Homebrew, `o4 update` doesn't replace it and tells you
to run `brew upgrade open4rena/tap/o4` instead.

You can also install again with the method you used before:

<Tabs>
  <Tab title="Install script">
    Run the install script again. It downloads the latest release and replaces
    the binary in the install folder.

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

    If you installed into a custom folder, set `O4_INSTALL_DIR` again.
  </Tab>

  <Tab title="Homebrew">
    ```bash theme={null}
    brew upgrade open4rena/tap/o4
    ```
  </Tab>

  <Tab title="Release archive">
    Repeat the download, checksum, and install steps. `install` replaces the
    old binary.
  </Tab>
</Tabs>

A session that was already running keeps using the old binary until you
restart it. While a session waits at the prompt, o4 checks the file it was
started from. If that file has been replaced, o4 shows
`new o4 installed · restart to update` on the second row below the prompt
until you restart. Quit, then run the `o4 resume <session-id>` command from
the summary o4 prints when it exits, to continue the same session on the new
version.

## Uninstall o4

Remove the binary with the method you used to install it:

<Tabs>
  <Tab title="Install script or archive">
    ```bash theme={null}
    rm ~/.local/bin/o4
    ```

    If you set `O4_INSTALL_DIR`, remove `o4` from that folder instead.
  </Tab>

  <Tab title="Homebrew">
    ```bash theme={null}
    brew uninstall open4rena/tap/o4
    ```
  </Tab>
</Tabs>

Removing the binary leaves your data in place. o4 keeps your settings, saved
API keys, sessions, and logs in `~/.o4`. To remove them too:

```bash theme={null}
rm -rf ~/.o4
```

<Warning>
  Deleting `~/.o4` removes every saved session and any API keys you saved in
  o4. It can't be undone.
</Warning>

Projects you opened with o4 may also contain a `.o4` folder with project
settings and data. Those folders stay in place; delete them yourself if you
don't need them.