Installation
Get started

Installation

1. Installation#

RayuCode v3 ships as a single native Rust binary named rayu. There is no Node.js, npm, Bun, Python or sudo involved: the installer downloads one prebuilt executable, verifies its SHA-256 checksum, and puts it on your PATH.

The same rayu binary is the terminal agent, the background server, and the engine the VS Code extension talks to.

One command, any machine#

macOS / Linux

bash
curl -fsSL https://rayucode.com/install | bash

Windows (PowerShell)

powershell
irm https://rayucode.com/install.ps1 | iex

Run the PowerShell line in Windows PowerShell 5.1 or PowerShell 7 on Windows 10/11. Administrator access is not required.

Then open a new terminal and start it:

bash
rayu

If you prefer to read the script first: https://rayucode.com/install.sh (macOS/Linux) and https://rayucode.com/install.ps1 (Windows). Both are plain, auditable text and are byte-identical to the scripts in the public Choeng-Rayu/rayucode-v2 repository.

What the installer does#

  1. Detects your OS and CPU architecture: linux-x86_64, linux-aarch64, macos-x86_64, macos-aarch64, windows-x86_64, windows-aarch64.
  2. Downloads the matching release asset from Choeng-Rayu/rayucode-v2 releases and verifies it against SHA256SUMS. A mismatch aborts the install and leaves any existing installation untouched.
  3. Installs the launcher into ~/.local/bin/rayu on macOS/Linux (or %LOCALAPPDATA%\rayu\bin\rayu.exe on Windows) — never a system directory — and adds that directory to PATH.
  4. If an older Node v2 rayu is installed, the new Rust binary is installed and verified first, then the old CLI is renamed to rayu-legacy, keeping your settings, API keys and sessions in ~/.rayu. It then asks whether to remove rayu-legacy or keep it.
  5. If an npm install -g @rayu-dev/rayu-cli copy is shadowing the new binary, the installer moves it aside to rayu-legacy so rayu resolves to v3.

Verify the install#

bash
rayu --version
rayu version --json     # machine-readable build identity

rayu --version prints a single line such as rayu v3.0.0 (8b00e87). rayu version prints the version, semver, git hash, git tag, build time and whether this is a release build.

Supported platforms#

TargetTripleInstaller detects it as
Linux x86_64x86_64-unknown-linux-gnulinux-x86_64
Linux ARM64aarch64-unknown-linux-gnulinux-aarch64
macOS Apple Siliconaarch64-apple-darwinmacos-aarch64
macOS Intelx86_64-apple-darwinmacos-x86_64
Windows x64x86_64-pc-windows-msvcwindows-x86_64
Windows ARM64aarch64-pc-windows-msvcwindows-aarch64

Linux builds are produced in a manylinux2014 image and run on glibc 2.17+. On Windows, use Git Bash, WSL, or PowerShell for the installer; the installed rayu.exe needs no shell at all.

Options#

Installer flags go after -s -- when you pipe the script:

bash
# a specific v3 release
curl -fsSL https://rayucode.com/install | bash -s -- --version v3.0.0

# somewhere else, and leave my shell profiles alone
curl -fsSL https://rayucode.com/install | bash -s -- --dir ~/bin --no-modify-path

# automatically remove the legacy Node CLI after upgrading
curl -fsSL https://rayucode.com/install | bash -s -- --remove-legacy

# keep the legacy Node CLI as `rayu-legacy` without prompting
curl -fsSL https://rayucode.com/install | bash -s -- --keep-legacy

# all options
curl -fsSL https://rayucode.com/install | bash -s -- --help
FlagMeaning
--version <v>Install an exact v3.x release tag, e.g. v3.0.0
--dir <path>Launcher directory (default ~/.local/bin)
--no-modify-pathDo not touch shell startup profiles
--remove-legacyUninstall the legacy Node CLI as part of the upgrade
--keep-legacyKeep it as rayu-legacy, no prompt
--uninstall (alias --remove)Remove RayuCode binaries, keep ~/.rayu
--quiet, -qLess output, non-interactive

Environment equivalents: RAYU_INSTALL_DIR, RAYU_HOME, RAYU_VERSION, RAYU_RELEASE_REPO, RAYU_RELEASE_METADATA_BASE, RAYU_REMOVE_LEGACY, RAYU_KEEP_LEGACY.

On Windows, irm | iex cannot forward arguments. Download the script first:

powershell
irm https://rayucode.com/install.ps1 -OutFile install.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Version v3.0.0

That -ExecutionPolicy Bypass applies to the installer process only, and it also works when the current window blocks running downloaded .ps1 files.

Updating#

bash
rayu update

rayu update asks the release metadata endpoint for the newest build, downloads it, verifies SHA256SUMS, swaps the installed binary atomically, and reloads a running background server onto the new binary without dropping live sessions.

Inside a session, /update does the same thing in the background, and /reload reloads into the newest available binary. rayu server reload is the shell equivalent and preserves in-flight work.

Auto-update is on by default for release builds. Turn the startup check off either per run with rayu --no-update or permanently:

toml
# ~/.rayu/config.toml
[features]
check_updates = false

Pin an update channel with rayu update --channel stable or rayu update --channel preview, or in [features] update_channel.

Uninstalling#

bash
curl -fsSL https://rayucode.com/install | bash -s -- --uninstall

This removes the installed binaries and launcher. Your data stays in ~/.rayu (settings, sessions, memories, skills) so a reinstall picks up where you left off. Delete ~/.rayu yourself if you want a clean slate.

Legacy Node CLI (v2)#

Only if you specifically need the older Node/Bun CLI:

# macOS / Linux
curl -fsSL https://rayucode.com/install-rayu-legacy.sh | bash

The legacy installer provisions its own Node runtime under ~/.rayu and installs into ~/.rayu/bin. It is also available from npm (npm install -g @rayu-dev/rayu-cli). Running rayu update, or re-running the v3 installer, upgrades a legacy install to v3 and keeps the old binary as rayu-legacy.

Next#

Start with the Quickstart, or read Providers if you want to know exactly which model credentials v3 accepts.