Installieren und Ausführen aus einem vorgefertigten Binary#

Für den Fall, dass du bereits — oder nur — das opendray-Binary haben möchtest, ohne dass ein Installer-Wizard dein System anfasst. Dies ist der Pfad für:

• npm install -g opendray / npx opendray — das npm-Paket liefert das offizielle Go-Release-Binary (siehe README → npm / npx).
• Release-Downloads — schnapp dir opendray_*_<os>_<arch>.tar.gz von der Releases-Seite.
• Geskriptete / ephemere Umgebungen — CI-Runner, Golden Images, Config- Management (Ansible, Nix, Docker) oder jeder Host, auf dem du schon dein eigenes Postgres und deinen eigenen Process-Supervisor betreibst.

Das Binary ist das komplette Gateway — die Web-Admin-SPA ist eingebettet, daher wird keine Node-Runtime, kein separater Static-Server und nichts zum Bauen benötigt. Was es nicht tut: irgendetwas für dich einrichten. Das ist der Deal: Du bringst eine PostgreSQL-Datenbank und eine Methode, den Prozess am Laufen zu halten — und im Gegenzug wird nichts hinter deinem Rücken installiert, konfiguriert oder registriert.

Lieber alles fertig eingerichtet? Auf einer frischen Linux- / macOS-Box stellt der Einzeiler-Installer Postgres bereit, installiert die AI-CLIs, schreibt die Konfiguration und registriert einen Service in ~5–10 Minuten. Siehe README → Einzeiliger Installer oder den manuellen getting-started.md-Walkthrough.

Diese Anleitung führt dich in fünf Schritten von „Binary auf PATH" zu „laufendes Gateway" und zeigt anschließend, wie du es als Service betreibst.

Schritt 1 — Binary beschaffen#

Via npm (beliebiges OS mit Node ≥ 18)#

Das richtige Plattform-Binary (opendray-{linux,darwin}-{x64,arm64}) wird automatisch via optionalDependencies ausgewählt — es gibt keinen postinstall- Hook und keinen Netzwerk-Call beim Install. Übergib nicht --no-optional: das überspringt das Plattform-Paket und lässt den Launcher ohne Binary zum Ausführen zurück.

Via Release-Archiv#

Verifizieren#

Unterstützte Plattformen: Linux (x64, arm64) und macOS (x64, arm64). Natives Windows ist nicht verpackt — nutze WSL2 und folge dem Linux-Pfad.

Schritt 2 — PostgreSQL 15+ mit pgvector bereitstellen#

opendray speichert alles (Sessions, Memory, Audit-Log) in PostgreSQL, und sein Memory-Subsystem benötigt die pgvector- Extension. Unterstützte Server-Versionen: 15, 16, 17.

Wenn du bereits Postgres betreibst, erstelle eine Datenbank und eine CRUD-only- Role, dann aktiviere die Extension einmalig mit einem Superuser:

Sobald die Extension existiert, kann die CRUD-only-Role von opendray Migrationen durchführen, ohne weiteren Superuser-Zugriff zu benötigen. Weise opendray zur Laufzeit niemals eine Superuser-Role zu — gib ihm ein projektspezifisches Konto und rotiere dessen Passwort separat.

Schritt 3 — Konfigurieren#

opendray liest seine Konfiguration aus einer TOML-Datei oder rein aus Umgebungsvariablen (12-Factor) — Env-Variablen haben immer Vorrang vor der Datei. Die einzige harte Anforderung ist die Datenbank-URL; alles andere hat einen Standardwert.

Option A — Umgebungsvariablen (gut für Container / ephemere Hosts)#

Führe opendray serve ohne -config-Flag aus und es lädt alles aus der Umgebung.

Option B — config.toml#

Das Minimum, das bearbeitet werden muss:

Die vollständig annotierte Datei (Logging, Session-Idle-Erkennung, Backups, Vault, MCP) findest du in config.example.toml. Übergib sie mit -config config.toml an die nachfolgenden Befehle. Halte Secrets auf gemeinsam genutzten Hosts aus der TOML-Datei heraus — setze OPENDRAY_DATABASE_URL / OPENDRAY_ADMIN_PASSWORD via Env und lass die Datei nicht-geheim.

Schritt 4 — Schema anwenden#

Idempotent — ein erneuter Aufruf ist ein No-op, sobald das Schema aktuell ist. Dies muss vor dem ersten serve erfolgreich abgeschlossen sein.

Schritt 5 — Ausführen#

Dies läuft im Vordergrund (Ctrl-C stoppt es). Jetzt solltest du Folgendes haben:

Das ist ein vollständiges, laufendes Gateway. Für alles über einen schnellen Test hinaus führe es unter einem Supervisor aus, damit es Neustarts und Abstürze überlebt — weiter unten.

Als Service betreiben#

opendray serve ist genau das, was der Start-Befehl einer Service-Unit aufrufen sollte. opendray liefert gehärtete, betriebsfertige Units mit; die folgenden Schritte entsprechen dem README → Produktions-Deployment, das die maßgebliche Referenz ist (vollständiger Bootstrap, Sandboxing-Hinweise, Reverse-Proxy/TLS).

Linux — systemd#

Das Repo liefert eine gehärtete Unit unter deploy/systemd/opendray.service (führt migrate als ExecStartPre aus, Secrets via EnvironmentFile, on-failure-Restart, Syscall-/Filesystem-Sandboxing).

Kein systemd? (LXC ohne es, OpenRC, runit, s6, supervisord…) Weise deinen Supervisor auf opendray serve -config /etc/opendray/config.toml hin und führe opendray migrate einmalig als Pre-Start-Schritt aus. Siehe README → Produktions-Deployment §B.

macOS — launchd#

Das Repo liefert einen LaunchDaemon unter deploy/launchd/com.opendray.opendray.plist (startet beim Boot, startet bei Abstürzen neu, loggt nach /usr/local/var/log/opendray/).

Neustart: sudo launchctl kickstart -k system/com.opendray.opendray. Entladen: sudo launchctl bootout system/com.opendray.opendray.

Beide Units sind vollständig dokumentiert — einschließlich des Secrets-Layouts und warum MemoryDenyWriteExecute deaktiviert ist — in deploy/README.md.

Aktuell halten#

Wie du aktualisierst, hängt davon ab, wie du installiert hast:

• Via npm installiert — aktualisiere mit deinem Package-Manager. opendray update würde das Binary innerhalb von node_modules hinter dem Rücken von npm ersetzen und beim nächsten Install überschrieben werden — also nicht hier verwenden.

  [object Promise]

• Release-Download / Wizard-Installation — das Binary aktualisiert sich selbst in-place (lädt das neueste Release herunter, verifiziert dessen SHA-256, ersetzt sich atomar):

  [object Promise]

Fehlerbehebung#

the matching platform package "opendray-…" was not installed npm wurde mit --no-optional ausgeführt, oder die Installation wurde unterbrochen. Führe npm install -g opendray erneut aus (ohne --no-optional).

unsupported platform Das npm-Paket deckt nur Linux/macOS auf x64/arm64 ab. Für andere Ziele baue aus dem Source — siehe quickstart.md.

config: database.url is empty Weder OPENDRAY_DATABASE_URL noch [database].url ist gesetzt. Setze eines davon (Schritt 3).

connection refused bei migrate/serve Postgres läuft nicht oder der DSN ist falsch. Bestätige, dass der Server läuft und Host/Port/Zugangsdaten in deinem DSN korrekt sind.

pgvector / extension "vector" is not available Die Extension ist nicht auf dem Server installiert oder wurde nicht in der opendray-Datenbank aktiviert. Führe Schritt 2 erneut durch (OS-Paket installieren, dann CREATE EXTENSION vector als Superuser).

Port already in use Ändere OPENDRAY_LISTEN (oder listen in config.toml) auf einen freien Port.

Nächste Schritte#

• README → Produktions-Deployment — vollständige Deploy-Referenz (systemd / launchd / eigener Supervisor, Hardening, Reverse-Proxy)
• docs/operator-guide.md — Ops: Reverse-Proxy-/TLS- Topologie, verschlüsselte DB-Backups, Daten-Export/Import
• docs/integration-guide.md — externe Integration gegen die REST- + WebSocket-API erstellen
• docs/getting-started.md — die geführte All-in-One- Einrichtung, wenn du die Teile lieber nicht selbst zusammensetzen möchtest