Install OAR as an app

The OAR web UI is a Progressive Web App (PWA). Installed, it gets its own icon and its own window, and it starts without the browser's address bar and tabs. It is the same web UI the browser shows, served by your relay: there is nothing else to install on the device, and the relay keeps all sessions.

What it needs #

Installing, and push notifications, need a secure context: the relay must be reached over HTTPS, or through localhost. A relay on your network at a plain http address does not qualify, which is the usual reason to set up a tunnel for a phone: see Cloudflare Tunnel, SSH tunnel or Reverse proxy. Whether and how the browser then offers the install is the browser's rule.

Installing #

Open the relay in the browser of the device and sign in first (see First run). Then:

OAR also has its own ⬇ button, at the right of the header of the conversation list, next to + New Chat and Status (on a narrow screen, open the list with ☰):

• When the browser has offered its install prompt, the button's tooltip reads Install app to home screen. Pressing it opens that prompt. After you accept, OAR shows Install accepted. The app will appear on your home screen., and App installed. once the browser reports it.
• When the browser has offered none, the tooltip reads Show install instructions, and pressing the button shows a message with the steps for your platform (iPhone and iPad, Android, or any other device), the same as the table above.

The button is hidden in the installed app, and in a shared conversation, where installing is not offered.

Name and icon #

The installed app is named by Settings → General → Relay name (see Settings). It holds up to 60 characters; while it is empty the app is called OAR. The label under the icon is the name's first word, or its first 12 characters when that word is longer. The same name is what paired relays call this relay.

The name is stored on the relay and served in the app's manifest to every browser and address, so the LAN address and a tunnel address agree. The app belongs to the address it was installed from: a relay behind a reverse proxy under a path prefix (remotePath, see config.json) is its own app. A new install uses the name at the time you install. An app that is already installed on Android gets a new name through Chrome's normal manifest update: one confirmation prompt shows the new name, then the launcher label changes. What other systems do with a changed name is up to them.

The icon follows Theme: Day mode uses the light icon and a white launch background, Night mode the dark icon and a dark one. After you change the theme, the installed app's own launch screen updates when the system refreshes the app, which on Android can take a day.

To keep several relays apart on one device, install each from its own address and give each a different Relay name: each address is a separate app with its own icon and label.

Signing in inside the app #

The relay keeps a browser signed in with a cookie (see First run). When the installed app has no valid sign-in, it shows the sign-in box, Enter your access token to connect. Paste the token into the Access token field and press Connect. oar url prints the current token if you need it again. After oar setup --new-token, every device, installed apps included, has to sign in again.

How the app behaves #

Back button and back gesture #

The system back button or gesture never closes the installed app at once. Back closes the open file viewer (Added in 0.9.9) or sub-agent viewer, and nothing else. When there is nothing of that kind to close, the app shows Press back again to close the app; a second press, without touching the app in between, closes it. Back does not close dialogs, menus or the conversation list. The file viewer is described under Back on a phone and in the installed app, the sub-agent viewer under The sub-agent viewer.

Before your first touch, the browser lets back leave the app, and a page cannot change that. In a browser tab the back button stays the browser's.

Fullscreen #

The app opens in its own standalone window. On a narrow screen it also asks the system for fullscreen at your first touch, where the system allows it. OAR's own ⬇ install button and its fullscreen button are hidden in the app. The page uses the whole screen, notch included, and keeps its header below the top safe area.

Coming back from the background #

A brief app switch changes nothing: the app keeps its connection to the relay for 45 seconds after it goes to the background. After that it closes the connection. When you return, it reconnects at once and re-reads the conversation list and the current conversation, the model list, the state of the session workers, and open questions and plan boards, so what happened while you were away appears without you doing anything. The same happens when the device comes back online or wakes from sleep. While the relay cannot be reached, the status dot at the left of the conversation list header is grey and its tooltip reads Web relay unreachable; the app keeps trying.

While the app is in the foreground it tells the relay so, and the relay sends push notifications only when no device has the app in front.

Updates #

The web UI is served by the relay, so an update of OAR on the relay host changes the UI too. The installed app keeps a copy of its shell, but loads the page and its scripts from the relay first whenever it can reach it. When it starts and finds a newer version, it switches to it without asking you; if that fails once, it removes its stored shell and reloads. You do not reinstall.

Limits #

• Offline, the app can open its stored shell, but everything that needs the relay does not work: conversations, the file browser, sending a message. The app's calls to the relay are never stored.
• The install needs the secure context described under What it needs.