Install

OAR is a relay you run on your own machine. Installing it puts the oar command on that machine. On macOS and Linux one line does the whole job: it finds or fetches Node.js, installs OAR, writes the config and starts the relay. On Windows the installer needs Node.js to be there already, and you can always install with npm or from a git checkout.

Requirements #

Nothing else is required to install. You add providers after OAR runs.

macOS and Linux #

curl -fsSL oar.sh/install | sh

You can read the script first at oar.sh/install. It needs curl or wget, and tar when it has to fetch Node.js. It refuses to run as root: OAR installs per user, and nothing needs root.

What it does #

1. It looks at what the machine has and prints a plan: which Node.js it uses, where it installs OAR, what it writes to your shell profile, and how the relay will be started.
2. It asks Continue? [Y/n]. Enter or y goes on; any other answer changes nothing.
3. It installs the package @oar-sh/oar (the latest release unless you pin a version or channel).
4. It runs oar setup --defaults --start: it writes the config (a new auth token, access for this machine only, the first free port from 3333 on, or the port you set with OAR_PORT) and starts the relay. It prints the relay URL and a QR code.
5. It prints the version, tells you the relay is running and lists the commands oar, oar setup and oar doctor.

On Linux with a systemd user session, the relay is started as a systemd user service, so it is back after a reboot. Elsewhere (macOS, containers, WSL without systemd) it is started in the background, and oar start starts it again after a reboot.

Where it installs #

Which of three cases applies depends on the Node.js the machine has.

Only OAR uses its own Node.js. The oar command in ~/.local/bin puts that Node.js last on PATH, so a Node.js of your own still comes first in the relay's sessions.

In the last two cases, when ~/.local/bin is not on your PATH, the installer lists the change in its plan and then appends a comment line (# added by the OAR installer) and an export PATH line to your shell's startup file: ~/.zshrc for zsh, ~/.bash_profile for bash on macOS, ~/.bashrc for bash on Linux, ~/.profile otherwise. New terminals find oar; in the current one, run the export PATH=... line the installer prints.

Options #

Flags go after sh -s --. Variables go before sh.

Any other flag stops the installer with unknown option.

curl -fsSL oar.sh/install | sh -s -- --yes
curl -fsSL oar.sh/install | OAR_VERSION=0.9.19 OAR_PORT=3400 sh
curl -fsSL oar.sh/install | OAR_DRY_RUN=1 sh

Running it again #

The installer can run again at any time. It installs the package again (the latest release unless you pin one), so it also serves as an update. It keeps an existing config, reuses OAR's own Node.js if it is still new enough, rewrites the oar launcher, and adds the PATH lines to your profile only once.

Running it without a terminal #

Piped from curl, the script asks its question on the terminal. Without one, for example in a CI job, it stops with no terminal to ask on and changes nothing. Pass --yes in that case.

Where it stops #

• It has no Node.js build for musl systems such as Alpine, nor for CPUs other than x64 and arm64. Install Node.js 22.13 or newer yourself, then run the installer again.
• If nodejs.org cannot be reached, a download or checksum fails, or the downloaded Node.js does not run, it stops and installs nothing.
• Releases before 0.9.8 install the same way, but their oar setup cannot start the relay. The installer then only writes the config and does not start the relay.

Windows #

irm oar.sh/install.ps1 | iex

This needs PowerShell 5 or newer and Node.js 22.13 or newer already installed. Unlike the macOS and Linux installer it does not fetch Node.js, does not ask to confirm and does not start the relay. It does this:

1. Checks that node and npm exist and that Node.js is new enough.
2. Prints the plan.
3. Runs npm install -g --allow-scripts=@oar-sh/oar,better-sqlite3,koffi @oar-sh/oar.
4. Runs oar setup. In a terminal it asks whether to make a new auth token, the access (this machine only, or LAN), the port and, Added in 0.9.15 how the relay starts: at sign-in, at boot before anyone signs in (one administrator prompt), or not at all. It then writes the config and prints the relay URL.

Run oar start afterwards to start the relay; the autostart you picked starts it at the next sign-in or boot. oar autostart changes the mode later. What comes next is on First run.

Set the variable in the same PowerShell window before the command. The Windows installer has no OAR_PORT; oar setup asks for the port, or you run oar setup --port <port>.

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

If the install works but oar is not found, open a new terminal, then run oar.cmd setup.

npm #

npm install -g --allow-scripts=@oar-sh/oar,better-sqlite3,koffi @oar-sh/oar
oar setup

npm 12 runs no install script it was not told to allow. Two of OAR's dependencies (better-sqlite3, koffi) fetch their native binary in one: without them the install succeeds on npm 12 and the relay then fails to start. Added in 0.9.14 OAR's own (@oar-sh/oar) copies the data an earlier version kept inside the package before npm removes it; see Upgrade notes for 0.9.14. npm 10 and 11 accept the flag and need none. The installers, oar update and the Update button pass it themselves.

oar setup creates the config and prints the relay URL, but it does not start the relay unless you pass --start. Use oar start afterwards. The global folder of npm must be writable and its bin folder must be on your PATH; npm prefix -g shows where it is. If it needs root, do not use sudo: run the installer on macOS or Linux instead. To update later, run oar update.

From a git checkout #

git clone https://github.com/oar-sh/oar
cd oar
npm install
node bin/oar.js setup   # writes server/config.json with a fresh auth token
npm start               # the same as: node server/server.js

A checkout differs from a global install in three ways:

• State lives inside the repository: server/config.json, server/data/, server/uploads/ and server/logs/. A global install keeps its state in ~/.oar (see Where OAR keeps its files and Files and folders).
• It never updates itself. Update with git pull, npm install, then restart the relay with 🌄 Restart web relay in a conversation's ⋯ menu. oar update is for global installs.
• oar start, oar stop and oar restart are for global installs only. In a checkout, npm start runs the relay in the foreground.

node server/server.js --port <port> --token <token> overrides the config for one run without saving it.

By platform #

After a reboot, oar start starts a relay that runs in the background.

WSL #

Run the Linux installer inside the distro, not in Windows. In WSL's default networking a port can be free inside the distro while a Windows program listens on it, and localhost:<port> in a Windows browser then reaches that program. A new config therefore takes the first port that is free on both sides, and oar setup refuses a port Windows holds. oar status, oar start and oar doctor warn when Windows holds the relay's port. To fix it, choose another port:

oar setup --port 3400

A LAN address inside WSL is internal to WSL. For phone access use a tunnel or WSL's mirrored networking.

Removing OAR #

Added in 0.9.15 oar uninstall takes OAR off the machine and keeps your data:

oar uninstall

It stops the relay (waiting for running turns), removes the autostart entries OAR generated (the systemd unit, or the Windows sign-in entry and boot task, with one administrator prompt for the boot task) and the Copilot extension wrapper OAR wrote, and has npm remove the package once the command has ended. Entries you made or edited by hand stay and are named. Your config, database, uploads and logs stay in the state folder, and the command prints where; a later install picks them up again. oar uninstall has the details and every message.

To delete the data as well:

oar uninstall --purge

It deletes the state folder after you type delete, and asks separately before it deletes a data folder outside it, one in a git checkout, or rescued-package-data. It refuses a drive root, your home folder, a system folder and any folder without OAR's config or database in it. This deletes your conversations.

oar uninstall does not undo what the macOS and Linux installer added outside the package:

• the oar script in ~/.local/bin, when the installer put it there (its second and third case);
• the two lines it added to your shell's startup file, if any (the comment # added by the OAR installer and the export PATH line below it);
• ~/.oar/runtime, OAR's own Node.js, if it is there. It sits in the state folder, so it stays without --purge.

Before 0.9.15, or when oar no longer runs, take the parts out by hand: stop the relay with oar stop and run oar service remove where a service or Windows autostart is set up; remove the package with npm uninstall -g @oar-sh/oar, or after the installer's other two cases delete ~/.oar/npm; then the parts above, and ~/.oar or %APPDATA%\oar only if you want your data gone.

Where OAR keeps its files #

A global install keeps its state in ~/.oar (%APPDATA%\oar on Windows; OAR_STATE_ROOT moves it):

• config.json
• data/, with the database and uploads
• logs/, with server.log and server-err.log when oar started the relay and a worker-<session>.log for each Node session worker

Updating the package with npm never touches these. The macOS and Linux installer may add two folders there that are not state: npm/ (the package, when npm's global folder was not writable) and runtime/node/ (OAR's own Node.js). oar doctor prints the paths in use.

What you have afterwards #

• The oar command. In a terminal, oar alone opens a menu with the relay's status and the other commands. oar setup changes the settings (access for other devices, port, token), and oar url prints the relay URL again.
• A config with a fresh auth token. With the default access, the relay is reachable on this machine only, at http://localhost:3333/ or the next free port.
• On macOS and Linux: a running relay. On Windows and after a manual npm install: a relay you start with oar start.

Check what is installed:

oar --version
oar doctor

oar doctor prints the version, Node.js, install mode, state folder, config path, port, whether a token is set, the database path and size, and which provider CLIs answer. It changes nothing.

Troubleshooting #

For problems after the install, see Troubleshooting.