First run

Once the oar command is installed (see Install), three things stand between you and a conversation: the relay needs a config (a port, who may reach it, and an access token), it needs to be running, and your browser needs to sign in with the token. This page walks through them in that order.

Setup #

oar setup writes the config file, config.json in OAR's state folder (~/.oar on macOS and Linux, %APPDATA%\oar on Windows; the environment variable OAR_STATE_ROOT moves it). It sets three things, and on Windows also the autostart:

The installer for macOS and Linux has already run oar setup --defaults --start for you, so a relay is running with those defaults and the installer printed its address. The Windows installer ends by running oar setup, which asks the questions below but does not start the relay: run oar start next. After a manual npm install -g, run oar setup yourself, then oar start.

In a terminal, oar setup asks three questions and shows the current value each time, so Enter keeps it. Added in 0.9.15 On Windows it asks a fourth, how the relay starts (Autostart):

New auth token? It signs every device out.
Access: 1 = this machine only, 2 = LAN (other devices on your network) [1]:
Port [3333]:
Autostart: 1 = at sign-in, 2 = at boot, before anyone signs in (one administrator prompt), 3 = off [3]:

At boot asks for one administrator confirmation on the PC; a declined prompt changes nothing, and setup still writes the config.

The port you choose must be free. Setup does not accept a port that another program holds, and on WSL one that Windows holds: with --port it stops, and at the question it asks again. The relay of this same install may keep its own port.

Setup also takes options. Give any of --port, --lan, --local, --new-token or --autostart and setup asks nothing at all; whatever you did not give keeps its current value.

When a relay is running and you change the token, the port or the access, setup restarts it so the change takes effect. In a terminal it asks first (The relay is running. Restart it now to apply the change?); with --defaults, or without a terminal, it restarts at once. If you answer no, the running relay keeps its earlier settings until oar restart.

At the end, setup prints the relay address, and a QR code when a phone can reach it (see From a phone).

Starting and stopping #

Run oar with no arguments in a terminal to get a menu: a header with the relay's status (running or stopped, version, address, port, access, service) and an entry for each command. Use the arrow keys or a digit and Enter; q quits. Outside a terminal, oar prints the status and the usage instead.

The commands you need first:

oar start prints a line like this:

[oar] Relay URL: http://localhost:3333/?token=<your token>

Treat that address like a password: it carries the token. With access set to this machine only, a second line says so and names the two ways to reach it from a phone: LAN access or a tunnel.

Opening the relay #

Open the printed address in a browser on the machine that runs the relay. The ?token= part signs you in. The relay then keeps the browser signed in with a cookie that lasts 30 days, and the browser's address bar drops the token. The cookie is HttpOnly, and it is marked Secure when you reach the relay over HTTPS.

Without the token in the address, the relay shows a sign-in box that says Enter your access token to connect. Paste the token and press Connect. A wrong one shows Invalid token.

From a phone #

For a phone or another computer on the same network, switch on LAN access:

oar setup --lan

If the relay runs, setup restarts it (in a terminal it asks first). It prints an address with your machine's network address in place of localhost, together with a QR code. Scan it with the phone. oar url prints the same address and code later. The QR code appears only when the relay has LAN access and the machine has a network address; with LAN access on and no network address, the command says so. On WSL with its default networking the address is internal to WSL and other devices cannot reach it, so setup prints no code: use a tunnel, or switch WSL to mirrored networking (networkingMode=mirrored in .wslconfig).

The address is plain http. Beyond your own network, use one of OAR's tunnels, which add HTTPS (see From outside your network).

If you lose the token #

oar url prints the address with the current token in it. If you would rather have a new one, run oar setup --new-token: it writes a new token and restarts the relay (in a terminal it asks first), and every device that was signed in has to sign in again with the new address.

The first look #

The first screen is the empty conversation view. What it says depends on the relay:

• Set up a provider, when no provider is ready. It offers Open Settings and + New chat. GitHub Copilot is the default provider; it needs a signed-in Copilot CLI on the relay host. The others are switched on under Settings → Providers. Providers at a glance says what each one needs.
• Start your first chat, when a provider is ready. + New chat is the main button.

⚙️ Settings is in the ⋯ menu at the top of a conversation, and the empty screen has a button for it too. On a narrow screen, the ☰ button shows the conversation list.

+ New Chat in the sidebar opens the dialog where you choose provider, model and working folder. Starting a conversation describes it field by field.

Keeping it running #

oar start runs the relay until you stop it or the machine restarts. To start it at every login, oar service install sets that up on Linux with a systemd user session and on Windows; the menu has an entry for it. Added in 0.9.15 On Windows, oar autostart boot starts it at boot instead, before anyone signs in. It is not available on macOS yet: start the relay with oar start there.

From outside your network #

OAR has built-in tunnel support for reaching the relay from outside your network over HTTPS: a Cloudflare Tunnel or an SSH tunnel. Read What OAR exposes first.

If it does not start #