Der Befehl oar

oar ist die Befehlszeile des Relay-Rechners. Es schreibt die Config, startet und stoppt das Relay, gibt die Adresse aus, die du im Browser öffnest, installiert den Dienst für den Start bei der Anmeldung, aktualisiert OAR, prüft die Installation und entfernt sie wieder. Es arbeitet mit der Installation, aus der es gestartet wurde, auf dem Rechner, auf dem es läuft; mit einem Relay auf einem anderen Rechner spricht es nicht.

Führ oar ohne etwas dahinter aus, um ein Menü zu bekommen, oder oar help für den Hilfetext. Wie du OAR installierst, steht unter Installation, der erste Start unter Erster Start.

Die Befehle #

Die meisten Meldungen beginnen mit [oar]. Fehler gehen auf die Standardfehlerausgabe, normale Ausgaben auf die Standardausgabe.

Wie die Befehlszeile gelesen wird #

• Der Befehl ist das erste Wort, das keine Option ist. Optionen dürfen davor stehen: oar --port 3400 setup ist oar setup --port 3400.
• --port, --migrate-from, --to und --autostart nehmen einen Wert, als nächstes Wort oder als --port=3400. Ohne Wert gibt oar --port needs a value. aus und endet mit 2. Für oar update --to und oar copilot --migrate-from nutze die Form mit Leerzeichen; siehe die Hinweise bei diesen Befehlen.
• --help oder -h vor einem -- gibt den Hilfetext aus und endet mit 0, egal was sonst in der Zeile steht.
• --setup, --start, --stop und --status nennen einen Befehl, wenn kein anderer angegeben ist: oar --setup --start ist oar setup --start.
• --install-extension, --no-install-extension, --migrate-from oder ein ---Teil ohne Befehl bedeuten oar copilot. --version oder -v ohne Befehl geben die Version aus.
• Jeder Befehl akzeptiert nur seine eigenen Optionen und gibt nach einer dieser Meldungen (auf die Standardfehlerausgabe) den Hilfetext aus, Exit-Code 2:

[oar] Unknown command: backup
[oar] Unknown option: --verbose
[oar] Unknown option for oar start: --port
[oar] Unexpected argument: extra
[oar] --lan needs a command.
[oar] oar start takes no "--" part.

Nur oar copilot nimmt einen ---Teil.

Das Menü: oar #

In einem Terminal zeigt oar die Version, ob das Relay läuft, die URL (ohne das Token), den Port, den Zugriff, den Zustand des Dienstes und jede Warnung, dann diese Einträge:

Bewege dich mit den Pfeiltasten (oder j und k) und drück Enter, oder drück eine Ziffer oder q. Nachdem ein Eintrag gelaufen ist, führt jede Taste zurück ins Menü. Strg+C in einer Frage führt zurück ins Menü; im Menü beendet es oar mit Exit-Code 130. Die Umgebungsvariable NO_COLOR schaltet Farben ab. Ein Terminal, das keine einzelnen Tasten lesen kann, bekommt dieselbe Liste mit einer Eingabeaufforderung Choose (1-9, q):.

Ist die Standardeingabe oder -ausgabe kein Terminal, gibt oar aus, was oar status ausgibt, eine Leerzeile und den Hilfetext, und endet mit 0, egal wie der Status ist.

oar setup #

oar setup [--port <port>] [--lan | --local] [--new-token] [--autostart signin|boot|off] [--defaults] [--start] [--migrate-from <dir>]

Schreibt config.json in den Zustandsordner von OAR (Wo oar seine Dateien ablegt; die Keys stehen unter config.json). Führ es nach der Installation aus und immer dann, wenn du einen anderen Port, Zugriff oder ein anderes Token willst. Einstellungen, die der Befehl nicht anfasst, bleiben in einer bestehenden Config, wie sie sind.

In einem Terminal und wenn du keine der Optionen --port, --lan, --local, --new-token, --autostart oder --defaults angibst, stellt es drei Fragen und zeigt den aktuellen Wert in eckigen Klammern; Enter behält ihn. Neu in 0.9.15 Unter Windows fragt eine vierte, wie das Relay startet, mit dem geltenden Modus als Vorgabe; sie entfällt, wenn der Start-Task nicht gelesen werden kann. Erster Start geht sie durch.

New auth token? It signs every device out. [y/N]
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]:

Ein Port ist frei, wenn nichts auf ihm antwortet und er auf diesem Rechner gebunden werden kann. Der Port des eigenen laufenden Relays dieser Installation zählt als frei. In WSL wird auch ein Port abgelehnt, den Windows belegt. Bei einer neuen Config, deren Port 3333 belegt ist, sagt das Setup Port 3333 is in use — using <port>. Eine globale Installation übernimmt außerdem einmal den Zustand aus dem früheren verwalteten Config-Ordner, ohne die Option.

Was es tut:

1. Migriert alten Zustand (globale Installationen): den früheren verwalteten Config-Ordner einmal von selbst oder den Ordner, den --migrate-from nennt. [oar] Migrated <folder or "earlier relay state"> into <state folder> (<n> items, sources untouched; receipt in backups/MIGRATION.md).
2. Schreibt config.json (Rechte 600 außerhalb von Windows) und gibt [oar] Wrote <path> aus. Eine neue Config enthält authToken, port, localhostOnly, pollIntervalMs (3000), processingTimeoutMs (600000) und conversationSessionMode (isolated).
3. Neu in 0.9.15 Stellt den Autostart um, wie --autostart oder die Frage es sagt (globale Installationen). Es führt oar autostart mit diesem Modus aus und gibt dessen Zeilen aus.
4. Läuft das Relay und haben sich Token, Port oder Zugriff geändert, startet es das Relay neu und wartet, bis es mit den neuen Einstellungen antwortet. In einem Terminal fragt es The relay is running. Restart it now to apply the change? [Y/n]; bei Nein gibt es The running relay keeps its earlier settings until it restarts: oar restart aus. Ohne Terminal startet es ohne Nachfrage neu.
5. Gibt die Relay-URL mit dem Token aus und einen QR-Code, wenn ein Handy die Adresse erreichen kann (LAN-Zugriff mit einer Netzwerkadresse, die nicht WSL-intern ist). Ist der Autostart-Schritt nicht durchgegangen, sagt es dann The config is written; the autostart step did not go through (see above). und endet mit 1.
6. Läuft das Relay nicht, sagt es, wie du es startest: oar start (mit einem Hinweis auf oar service install, wenn kein Dienst existiert); in einem Git-Checkout npm start.

oar start #

oar start

Startet das Relay im Hintergrund und gibt die Relay-URL aus (mit dem Token, ohne QR-Code). Es hat keine Optionen. Es braucht eine Config: Ohne eine gibt es No config yet — run: oar setup aus. Ein Git-Checkout wird abgelehnt (This is a git checkout — start the relay with: npm start). Beides endet mit 1.

• Ein Relay, das schon antwortet, bleibt unberührt: The relay is already running. It keeps the version and settings it started with until you restart it: oar restart.
• Läuft das Relay mit Einstellungen von vor einem oar setup, sagt oar start das und verweist auf oar restart.
• Ist ein systemd-Benutzerdienst installiert (Linux), wird der Dienst aktiviert und gestartet. Sonst startet das Relay als Hintergrundprozess, der das Terminal überlebt und server.log und server-err.log in den Log-Ordner schreibt. Führ nach einem Neustart des Rechners oar start erneut aus oder richte den Start bei der Anmeldung ein.
• Es wartet bis zu 20 Sekunden, bis das Relay antwortet, und hört früher auf zu warten, wenn der Prozess, den es gestartet hat, endet. Dann: The relay did not come up — see <log folder>/server-err.log (über den Dienst: see journalctl --user -u oar). Neu in 0.9.14 Hält ein lebendes Relay den Lock, nennt eine zweite Zeile den Lock und sagt, was zu tun ist: The lock <path> is held by relay process <pid> (started <time>): oar stop, or end process <pid>. Nennt der Lock einen Prozess, von dem sich nicht sagen lässt, ob er ein Relay ist: The lock <path> names process <pid>, which cannot be told to be a relay: if no relay is running, end process <pid> or delete the lock.
• Neu in 0.9.14 Ein Relay, das noch die Datenbank übernimmt, auf der es bisher lief (der erste Start nach dem Update auf 0.9.14), gilt nicht als fehlgeschlagen: oar start sagt The relay (process <pid>) is bringing over the database it ran on until now (…) and is still running; it answers once that is done. und nennt sein Log.
• Auf einen Lock, dessen Relay noch startet, wird bis zu 5 Sekunden gewartet. Der Lock einer früheren Version, deren Relay nicht antwortet, wird entfernt (Removing a leftover relay lock); Neu in 0.9.14 einen Lock, den diese Version geschrieben hat, überlässt es dem Relay, das einen veralteten selbst erkennt (siehe Ein Relay pro Datenordner).
• Ein Port, den ein anderes Programm belegt, oder ein Relay mit einem anderen Token: Port <port> is in use by another program, or by a relay with another token. und ein Hinweis, mit oar setup --port <port> einen anderen Port zu wählen.
• In WSL warnt es, wenn Windows den Port belegt (WSL).

Exit-Code 0: Das Relay läuft oder übernimmt noch seine Datenbank. Exit-Code 1: keine Config, ein Git-Checkout, der Port ist belegt oder das Relay ist nicht hochgekommen.

oar stop #

oar stop

Keine Optionen; braucht eine Config (Exit 1 ohne eine).

• Läuft der systemd-Dienst, führt es sofort systemctl --user stop oar aus und sagt The relay service is stopped. It starts again at the next boot (without lingering: at the next login); to take it out: oar service remove.
• Jedes andere Relay wird über seine eigene Schnittstelle gebeten zu stoppen und stoppt, sobald kein Turn läuft. Laufen Turns, wird Waiting for the relay's running turns to finish … ausgegeben. oar stop wartet bis zu 30 Sekunden und gibt dann The relay is stopped. oder The relay is still busy; it stops by itself when its running turns finish. aus. Beides endet mit 0.
• Kein Relay läuft: The relay is not running., Exit 0.
• Port von etwas anderem belegt: Port <port> is in use by another program, or by a relay with another token., Exit 1. Nennt die Lock-Datei einen lebenden Prozess dieser Installation, gibt eine zweite Zeile seine Prozess-ID an und sagt dir, ihn aus seiner Weboberfläche neu zu starten, mit ⋯ → Restart web relay (⋯ → Web-Relay neu starten), oder diesen Prozess zu beenden.
• The relay did not accept the stop request. oder ein fehlgeschlagenes systemctl: Exit 1.

Unter Windows und dort, wo der Dienst installiert ist, aber nicht läuft, wird das Relay über seine eigene Schnittstelle gestoppt. Was ein Stopp mit laufenden Turns macht, steht unter Das Relay neu starten.

oar restart #

oar restart

Startet ein laufendes Relay neu, damit es eine neue Version lädt und die Config erneut liest, und gibt dann die Relay-URL aus. Ein gestopptes Relay wird stattdessen gestartet, wie bei oar start. Keine Optionen; braucht eine Config.

• Läuft der systemd-Dienst, startet systemd ihn sofort neu; ein laufender Turn endet (Das Relay neu starten).
• Jedes andere Relay wird gebeten neu zu starten und wartet auf seine laufenden Turns. Der Befehl wartet bis zu 60 Sekunden, bis das Relay auf dem Port der Config mit dem Token der Config antwortet, und gibt dann The relay restarted. aus. Laufen noch Turns: The relay is still busy; it restarts by itself when its running turns finish., Exit 0. Neu in 0.9.13 Der Neustart wird eingereiht wie bei 🌄 Restart web relay: Die Browser zeigen sein Banner, und nach Ask after a queued relay restart has waited (Nachfragen, nachdem ein eingereihter Relay-Neustart gewartet hat) fragt es dort, ob jetzt neu gestartet, weiter gewartet oder abgebrochen werden soll (Der Neustart wartet).
• Exit 1 mit The relay came back on its earlier port and token: it was started with fixed ones (oar copilot). End that session, then run: oar start: Ein Relay, das oar copilot gestartet hat, behält den Port und das Token, die es bekommen hat.
• Exit 1 mit The relay did not accept the restart request. Restart it from the web UI (⋯ → Restart web relay). (Restart web relay), systemctl --user restart oar failed oder The relay did not come back — see <log folder>/server-err.log (über den Dienst: see journalctl --user -u oar).
• Ein Port, den etwas anderes belegt: die Meldung von oar stop, Exit 1.

oar status #

oar status

Gibt den Zustand des Relays aus und endet mit einem Code, den ein Skript prüfen kann.

[oar] OAR 0.9.19
[oar] The relay is running on port 3333 (this machine only): http://localhost:3333/
[oar] Service: installed, running

Exit-Code 0: Das Relay läuft. Exit-Code 3: Es ist gestoppt, der Port ist von etwas anderem belegt oder es gibt keine Config.

oar url #

oar url

Gibt die Adresse aus, die du im Browser öffnest, mit dem Auth-Token, so wie oar setup endet. Keine Optionen; braucht eine Config (Exit 1 ohne eine). Sonst Exit 0.

[oar] Relay URL: http://localhost:3333/?token=...
[oar] This machine only. For a phone, switch on LAN access (oar setup --lan) or use a tunnel (README: Remote access).

• Mit LAN-Zugriff ist die Adresse die erste nicht interne IPv4-Adresse des Rechners, und ein QR-Code dafür folgt auf die erste Zeile.
• Mit LAN-Zugriff, aber ohne Netzwerkadresse: LAN access is on, but this machine has no network address. Im Standard-Netzwerkmodus (NAT) von WSL ist die Adresse WSL-intern; die Ausgabe sagt das und nennt einen Tunnel oder den Mirrored-Netzwerkmodus als Auswege. In diesen Fällen kein QR-Code.
• Meldet das laufende Relay eine Tunnel-Adresse, folgt eine Zeile Tunnel URL: mit angehängtem Token und ein QR-Code dafür.
• Eine letzte Zeile sagt The relay is not running. Start it with: oar start oder, nach einer geänderten Einstellung, dass das Relay bis zu oar restart mit seinen früheren Einstellungen läuft.

oar update #

oar update [--beta] [--to <version>]

Installiert ein neueres Release von OAR aus npm und bittet ein laufendes Relay, neu zu starten. Es ist das Gegenstück im Terminal zum Button Update (Aktualisieren) in Settings → General (Einstellungen → Allgemein) (OAR aktualisieren). Ein Git-Checkout gibt This install runs from a git checkout — update with git pull, then restart the relay. aus und endet mit 1.

Was es tut:

1. Ohne --to holt es https://oar.sh/latest.json (5 Sekunden), bei jedem Lauf, egal ob die automatische Prüfung in der Weboberfläche an ist.
2. Ist die Version des Kanals nicht neuer als die laufende: Already up to date (<version>)., Exit 0.
3. Gibt Updating @oar-sh/oar <old> -> <new> ... aus und führt npm install -g @oar-sh/oar@<version> aus, mit dem Flag, das die Installationsskripte von OAR und seinen nativen Abhängigkeiten laufen lässt. Außerhalb von Windows nutzt es das npm neben dem Node.js, das oar ausführt, und installiert in das Präfix, in dem das Paket liegt; unter Windows npm.cmd. npm gibt seine eigene Ausgabe aus; dann Installed @oar-sh/oar@<version>.
4. Läuft ein Relay, bittet es dieses, neu zu starten, sobald die Queue untätig ist (Relay restart requested — it restarts once the queue is idle.); ohne Relay No running relay detected — the update loads on the next start. Eine Ablehnung gibt Could not request a relay restart; restart it manually to load the update. aus.

Exit-Code 0: installiert oder schon aktuell. Exit-Code 1: ein Git-Checkout; --to ist keine Version wie 0.9.2; das Manifest kann nicht geholt werden (Could not fetch <url>.), hat eine andere schemaVersion als 1 oder enthält keine nutzbare Version; npm install ist fehlgeschlagen (the running install is unchanged).

oar service #

oar service [install | remove | status]

Startet das Relay bei jeder Anmeldung. oar service allein ist oar service status. Ein Git-Checkout wird abgelehnt (Exit 1). Die Seite Das Relay automatisch starten erklärt den Dienst aus Sicht des Besitzers.

Linux #

Eine systemd-Benutzer-Unit, oar.service, in ~/.config/systemd/user/. Sie führt das Relay mit dem Config-, Daten- und Log-Ordner dieser Installation aus und mit dem PATH deiner Shell plus ~/.local/bin und dem Ordner des genutzten Node.js. systemd startet es 5 Sekunden nach einem Absturz neu.

Ohne systemd-Benutzersitzung sagt der Befehl das und endet mit 1. In WSL nennt die Meldung zusätzlich, wie du systemd einschaltest: systemd=true unter [boot] in /etc/wsl.conf, dann wsl --terminate <distro> aus Windows.

Windows #

Ein Eintrag in deinem Autostart-Ordner startet das Relay, wenn du dich anmeldest.

Ein Start beim Hochfahren über eine geplante Aufgabe wird mit oar autostart boot eingerichtet oder in der Weboberfläche unter Settings → General → Autostart (Windows) (Einstellungen → Allgemein → Autostart, Windows) (Windows). Solange diese Aufgabe bereit ist, lehnen install und remove ab (Exit 1) mit The relay starts at boot through a scheduled task. Change that with oar autostart signin|off, or in the web UI: Settings → General → Autostart (Windows).; status meldet sie.

macOS #

The service is not supported on macOS yet. Start the relay with: oar start, Exit 1 für jedes Wort.

Exit-Code 0: erledigt oder status. Exit-Code 1: ein Git-Checkout, macOS, keine systemd-Benutzersitzung, keine Config bei install, ein geplanter Start-Task unter Windows oder das Relay ist nach install nicht hochgekommen. Exit-Code 2: ein anderes Wort als die drei oder ein zweites Wort.

oar autostart Neu in 0.9.15 #

oar autostart [signin | boot | off | status] [--replace]

Stellt um, wie das Relay dieser Installation von selbst startet. oar autostart allein ist oar autostart status. Ein Git-Checkout wird abgelehnt (This is a git checkout — autostart is for global installs., Exit 1). signin und boot brauchen eine Config; off und status nicht. Autostart erklärt die Modi aus Sicht des Besitzers.

Windows #

Die Administrator-Abfrage erscheint auf dem Desktop des PCs selbst, und es wird bis zu 2 Minuten auf sie gewartet. Nur der Aufruf von schtasks läuft mit erhöhten Rechten. Eine abgelehnte Abfrage ändert nichts (Nothing changed: the administrator prompt was declined.). Nach einem Wechsel mit --replace wird jede Kopie genannt: Kept a copy of <entry> as <copy>. Ein Wechsel, der nach der Abfrage fehlschlägt, stellt die Tasks wieder her, die er gelöscht hat, und seine Fehlerzeile endet mit Copies kept: ….

Nur Einträge, die OAR erzeugt hat, werden gelöscht oder überschrieben. Solange ein von Hand angelegter oder bearbeiteter Eintrag neben dem neuen Modus stehen bliebe oder durch ihn ersetzt würde, ändert sich nichts, und der Eintrag wird genannt; siehe Einträge, die OAR nicht angelegt hat.

Ein Start-Task, der nicht gelesen werden kann (z. B. Access is denied), stoppt jeden Wechsel, auch mit --replace: Nothing changed: the boot task could not be read (<reason>).

Linux und macOS #

Unter Linux bilden die Wörter auf oar service ab: signin und boot führen oar service install aus, off führt oar service remove aus, status führt oar service status aus. Mit Lingering startet der Dienst beim Hochfahren. Unter macOS: Autostart is not supported on macOS yet. Start the relay with: oar start, Exit 1.

Exit-Code 0: erledigt oder status. Exit-Code 1: ein Git-Checkout, macOS, keine Config bei signin oder boot, ein selbst angelegter Eintrag im Weg, eine abgelehnte oder fehlgeschlagene Administrator-Abfrage, ein Start-Task, der nicht gelesen werden kann, oder ein Anmelde-Eintrag, der nicht geändert werden kann; unter Linux die von oar service. Exit-Code 2: ein anderes Wort, ein zweites Wort oder eine andere Option.

oar uninstall Neu in 0.9.15 #

oar uninstall [--purge]

Nimmt OAR vom Rechner und behält deine Daten. Ein Git-Checkout wird abgelehnt (This is a git checkout — there is no global package to uninstall., Exit 1). Mit --purge stellt es zuerst seine Fragen (unten); dann, der Reihe nach:

1. Stoppt das Relay, wie oar stop es tut: Es wartet auf laufende Turns. Ein Relay, das danach noch beschäftigt ist, beendet den Befehl (The relay finishes its running turns first; it stops by itself after them.), und sonst wird nichts geändert. Ein Relay, das seinen Lock hält, ohne zu antworten, während es eine Datenbank übernimmt oder startet, beendet ihn auch: The relay (process <pid>) is bringing over its database and does not answer yet; once oar status says it runs, run oar uninstall again. oder A relay (process <pid>) holds <lock> without answering; stop it (oar stop, or end process <pid>).
2. Entfernt die Autostart-Einträge, die OAR für diese Installation erzeugt hat: unter Windows den Start-Task (eine Administrator-Abfrage) mit seinem Starter und seiner Task-XML sowie den Anmelde-Eintrag; unter Linux die systemd-Unit, wenn es die ist, die oar service install geschrieben hat. Dann den Wrapper der Copilot-Extension in ~/.copilot/extensions/web-relay/, den OAR für diese Installation geschrieben hat. Ein Eintrag oder Wrapper, der von Hand angelegt oder geändert wurde oder zu einer anderen Installation gehört, bleibt und wird genannt (Left as it is: <path> (hand-made)).
3. Mit --purge löscht es die Daten (unten).
4. Startet npm uninstall -g @oar-sh/oar im Hintergrund, mit dem npm neben dem Node.js, das oar ausführt, und in dem Präfix, in dem das Paket liegt (unter Windows npm.cmd). npm kann ein Paket nicht entfernen, während es läuft, daher wartet das, bis oar beendet ist (bis zu 2 Minuten), und schreibt dann das Ergebnis von npm in oar-uninstall.log: im OAR-Ordner logs oder mit --purge im Temp-Ordner.

Es endet mit dem, was es getan hat:

[oar] Done: stopped the relay.
[oar] Done: removed C:\Users\dev\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\oar-web-relay.cmd.
[oar] Your data stays in C:\Users\dev\AppData\Roaming\oar (config, database, uploads, logs). A later install picks it up again; delete the folder yourself if you no longer need it.
[oar] npm removes @oar-sh/oar once this command has ended (log: C:\Users\dev\AppData\Roaming\oar\logs\oar-uninstall.log).

Liegt der Datenordner außerhalb des Zustandsordners, nennt die Zeile beide. Session-Worker laufen weiter, wenn das Relay stoppt, und npm kann die Dateien nicht entfernen, die ein laufendes Programm hält. Laufen noch Programme aus dem Paket, nennt der Befehl ihre Prozess-IDs, und npm lässt ihre Dateien in einem versteckten Ordner .oar-* neben dem früheren Ort des Pakets zurück; das Log nennt diesen Ordner. Lösch ihn, sobald sie beendet sind, spätestens nach einem Neustart des Rechners.

Schlägt ein Schritt fehl, stoppt der Befehl mit dem Grund (z. B. Uninstall stopped: <reason>. oder The relay did not stop.), dann Done: … und Not done: the autostart entries; the package. (mit --purge auch the data) und Run oar uninstall again once that is sorted out. (mit --purge: oar uninstall --purge).

Mit --purge bekommen manche Ordner nach dem delete eine eigene Frage, [y/N]: der Zustandsordner, wenn er in einem Git-Checkout liegt, rescued-package-data (Daten, die eine frühere Version in ihrem Paket abgelegt hat), und ein Datenordner außerhalb des Zustandsordners (dataDir in der Config oder COPILOT_WEB_RELAY_DATA_DIR). Egal was du eingibst, --purge löscht nichts in einem Zustandsordner, der die Wurzel eines Laufwerks oder Dateisystems ist, dein Home-Ordner oder ein Ordner darüber, ein Systemordner oder ein Ordner darüber, ein Ordner im Windows-Ordner, ein Git-Checkout oder ein Ordner ohne OAR-Config oder -Datenbank darin: --purge deletes nothing in <folder> (<reason>). Nothing was changed. Ein zusätzlicher Ordner dieser Art wird nicht angeboten (Not deleted, and not offered: …).

Exit-Code 0: Das Entfernen des Pakets ist gestartet. Exit-Code 1: ein Git-Checkout; ein Zustandsordner, den --purge ablehnt; delete nicht eingetippt; ein Relay, das nicht gestoppt ist oder seinen Lock hält, ohne zu antworten; ein Autostart-Eintrag, der nicht entfernt werden konnte (eine abgelehnte Abfrage, ein Start-Task, der nicht gelesen werden kann); ein Ordner, der nicht gelöscht werden konnte; npm konnte nicht gestartet werden (remove it yourself: npm uninstall -g @oar-sh/oar). Exit-Code 2: eine andere Option. Exit-Code 130: Strg+C bei einer Frage.

oar copilot #

oar copilot [--port <port>] [--install-extension] [--no-install-extension] [--migrate-from <dir>] [-- <gh copilot args>]

Startet das Relay, wenn keines antwortet, und führt dann die GitHub Copilot CLI (gh copilot) in deinem Terminal aus. Ein Relay, das es gestartet hat, stoppt, wenn die Session endet. GitHub Copilot erklärt, wann du es nutzt. Dieselben Optionen ohne das Wort copilot führen es auch aus: oar -- <args>, oar --install-extension, oar --port 3400 --no-install-extension.

Der Reihe nach: prüft, dass gh existiert; erneuert den Wrapper (ein Fehler wird gemeldet und stoppt nur --install-extension); migriert alten Zustand (globale Installationen); sucht das Relay auf dem Port; startet es, wenn es nicht antwortet, und wartet bis zu 20 Sekunden (Relay did not become ready at <url>); dann führt es gh copilot im aktuellen Ordner mit angeschlossenem Terminal aus. Ein Relay, das schon lief, läuft weiter. Eine fehlende Config wird mit Zugriff nur für diesen Rechner angelegt.

--help oder -h vor dem -- gibt den allgemeinen Hilfetext aus, keinen für copilot. Ein --help oder -h nach dem -- gibt die Hilfe von oar copilot aus und endet mit 0. --install-extension und --no-install-extension nach dem -- liest oar ebenfalls. Keine davon erreicht gh.

Das Relay einer Copilot-Session hat den Port und das Token, mit denen es gestartet wurde. oar restart kann es nicht verschieben; siehe oar restart.

oar doctor #

oar doctor

Gibt aus, was oar findet. Keine Optionen, ändert nichts, endet mit 0.

OAR 0.9.19
  node          : v22.13.0 (linux)
  mode          : global install
  state root    : /home/dev/.oar
  config        : /home/dev/.oar/config.json
  port          : 3333 (localhostOnly: yes)
  auth token    : set
  tunnel        : disabled
  database      : /home/dev/.oar/data/copilot.db (12.4 MB)
  provider CLIs :
    gh (Copilot)  : gh version 2.60.0 (2025-01-01)
    claude        : 2.1.0 (Claude Code)
    grok          : not found
    cursor        : bundled (@cursor/sdk)

oar help und oar version #

oar help          # also: oar --help, oar -h, oar <command> --help
oar version       # also: oar --version, oar -v

help gibt den Hilfetext aus. version gibt die installierte Version aus, z. B. 0.9.19. Beide enden mit 0. --version und -v funktionieren nur ohne Befehl.

Wo oar seine Dateien ablegt #

oar arbeitet mit einer Installation: dem Paket, aus dem es gestartet wurde, und dessen Zustandsordner.

OAR_STATE_ROOT verschiebt den Zustandsordner einer globalen Installation. Ein Paketordner, der .git enthält, gilt als Git-Checkout. Der Datenordner enthält die Datenbank copilot.db, die Lock-Datei relay-server.lock und, zwischen einem oar setup und dem Neustart, der es übernimmt, relay-previous.json. Die Logs sind server.log und server-err.log. Andere Orte, an die oar schreibt: ~/.config/systemd/user/oar.service (Linux-Dienst), oar-web-relay.cmd im Windows-Autostart-Ordner, oar-web-relay-launcher.cmd, die XML des Start-Tasks, oar-relay-elevate.ps1, oar-web-relay.log und oar-web-relay-launcher.log in %APPDATA%\oar sowie ~/.copilot/extensions/web-relay/extension.mjs. Neu in 0.9.15 oar autostart --replace legt seine Kopien als <name>.bak im Zustandsordner ab, und oar uninstall schreibt oar-uninstall.log in den Log-Ordner (mit --purge in den Temp-Ordner).

Umgebungsvariablen #

Wie oar das Relay findet #

oar liest Port und Token aus der config.json der Installation und fragt http://localhost:<port>/api/status mit dem Token an:

Eine Lock-Datei ist kein Beweis: Sie kann ihr Relay überleben. oar start und oar copilot warten auf ein Relay, das sie hält und noch nicht antwortet, und entfernen nur einen Lock, den eine frühere Version geschrieben hat. oar update nimmt einen lebenden Lock als laufendes Relay. oar uninstall macht nicht weiter, solange ein lebender Prozess ihn hält. Zwischen einem oar setup, das Port oder Token geändert hat, und dem Neustart, der es übernimmt, antwortet das Relay noch auf den alten Werten; oar findet es über relay-previous.json und sagt, dass es mit seinen früheren Einstellungen läuft.

Ist der Dienst installiert, gehen start, stop und restart unter Linux über systemd (sofort, ohne auf Turns zu warten); sonst startet start einen abgekoppelten Prozess, und stop und restart nutzen die eigene Schnittstelle des Relays, die wartet, bis kein Turn läuft. Unter Windows ist der Autostart nie an start beteiligt; status zeigt Service: installed, wenn der Autostart oder der Start-Task an ist.

WSL #

In WSL erkennt oar die Distribution (WSL_DISTRO_NAME oder WSL_INTEROP oder das Kernel-Release) und fragt Windows, welches Programm einen Port belegt. oar setup lehnt einen Port ab, den Windows belegt. oar setup, start, status und doctor geben Windows holds port <port> (<program>): a browser on Windows reaches that program, not this relay. Pick another port: oar setup --port N aus. Mit LAN-Zugriff im Standard-Netzwerkmodus von WSL sagt oar url, dass die Adresse WSL-intern ist.

Exit-Codes #