Agent auf macOS bereitstellen

Diese Anleitung führt dich durch die Installation und Registrierung des octoja Agents auf einem macOS-System.

Voraussetzungen

• macOS 12 (Monterey) oder neuer. Für Remote Desktop-Sitzungen auf den Mac ist macOS 14 oder neuer erforderlich.
• Die Berechtigung Agent-Verwaltung in octoja — ohne sie ist die Seite Agent-Bereitstellung nicht verfügbar. Berechtigungen erhältst du über deine Gruppenmitgliedschaften unter Administration → Gruppen.
• Admin-Konto auf dem Mac
• Internetzugang (ausgehend HTTPS auf Port 443)

Über die Enrollment-Einstellungen

Die Agent-Bereitstellungsseite öffnet sich mit Schritt 1 – Einstellungen, in dem du festlegst, wie sich neue Agents authentifizieren. Zur Auswahl stehen zwei Karten: Offenes Deployment („Jedes Gerät mit der URL kann sich registrieren.“) und Token-basiertes Deployment. octoja erstellt Tokens nie von selbst — wählst du Token-basiertes Deployment, öffnet sich der Dialog Deployment konfigurieren, in dem du optional Kunde, Standort und Ablaufdatum zuweist und den Installations-Token ausdrücklich erstellst. Der Installationsbefehl, der später in Schritt 4 – Installieren angezeigt wird, bettet diesen Token automatisch ein, sodass du den Befehl nur wortgetreu kopieren musst.

Das „…“-Menü in der Kopfzeile der Seite bietet Token verwalten — damit öffnest du die Seite Enrollment-Tokens, auf der du Tokens erstellen und löschen kannst. Diese Seite listet die Tokens der Kunden auf, die du erreichst; Tokens, die für alle Kunden gelten, bleiben Konten vorbehalten, die auch alle Kunden erreichen. Die instanzweite Vorgabe findest du als Administrator unter Einstellungen → Richtlinie zur Agent-Registrierung; deaktiviere dort Offenes Deployment erlauben, um für jeden neuen Agent einen Enrollment-Token zu verlangen.

Schritte

1. Navigiere in octoja zu Administration → Agent-Bereitstellung. Die Seite ist als fünf nummerierte Karten aufgebaut: Einstellungen, Plattform wählen, Installationsmethode wählen, Installieren und Verifizierung.
2. Wähle in Schritt 1 – Einstellungen Offenes Deployment (kein Token erforderlich) oder Token-basiertes Deployment — und erstelle den Installations-Token, wenn der Dialog dich dazu auffordert.
3. Klicke in Schritt 2 – Plattform wählen auf macOS.
4. Wähle in Schritt 3 – Installationsmethode wählen die Schnellinstallation oder Manuelle Installation aus.
5. Kopiere in Schritt 4 – Installieren den Befehl oder lade das ZIP-Archiv aus dem Bereich herunter.
6. Schritt 5 – Verifizierung bestätigt, dass sich der Agent gemeldet hat.

Schnellinstallation

Kopiere den Befehl wortgetreu aus der Karte Installieren und füge ihn im Terminal auf dem Mac ein. Das install.sh-Skript wird auf dem octoja-CDN gehostet, nicht auf deiner octoja-Instanz — kopiere den vollständigen Befehl, anstatt die URL abzutippen:

curl -fsSL '<install.sh-URL aus der Karte „Installieren">' | sudo bash -s -- 'https://YOUR-OCTOJA-URL'

Beim Token-basierten Deployment hängt octoja den Token als zweites positionelles Argument an — übernimm auch hier den Befehl vollständig:

curl -fsSL '<install.sh-URL aus der Karte „Installieren">' | sudo bash -s -- 'https://YOUR-OCTOJA-URL' 'YOUR-TOKEN'

Das Mac-Admin-Passwort wird abgefragt.

Manuelle Installation (.pkg)

1. Lade in Schritt 4 – Installieren das Archiv octoja_osx-<arch>.zip aus dem Bereich Manuelle Installation herunter (wähle über den Tab ARM64 oder X64 die passende Architektur) und entpacke es. Das Archiv enthält das Paket (octoja_<version>_<arch>.pkg) und das Installationsskript install.sh nebeneinander.
2. Öffne das Terminal (Programme → Dienstprogramme → Terminal), wechsle in den entpackten Ordner und führe install.sh aus — das Skript ist der Installer für den manuellen Weg:

sudo bash install.sh https://YOUR-OCTOJA-URL

Beim Token-basierten Deployment übergibst du den Token als zweites Argument:

sudo bash install.sh https://YOUR-OCTOJA-URL YOUR-TOKEN

Das Skript prüft zuerst, ob dein octoja-Server erreichbar ist, schreibt dann die Verbindungseinstellungen nach /opt/octoja/etc/installer.settings.json und installiert anschließend das .pkg über den nativen macOS-Installer. Die Agent-Dienste starten automatisch — es erscheint kein Installationsfenster.

Installiere nicht per Doppelklick auf die .pkg-Datei. Ohne die Verbindungseinstellungen kennt das Paket deine octoja-Server-URL nicht — die Installation schlägt fehl und die Agent-Dienste werden nicht gestartet. Installiere immer über install.sh oder über die unten beschriebene Sidecar-Datei.

Die Karte Schritt 5 – Verifizierung der Agent-Bereitstellungsseite bestätigt den Rest: „Geschafft! Der Agent erscheint innerhalb von Sekunden auf der Geräteseite — bereit zur Verwaltung.“ Öffne Geräte, um deinen neuen Mac zu sehen.

Alternative: Sidecar-JSON-Datei

Für unbeaufsichtigte Installationen — zum Beispiel per MDM — kannst du die Verbindungseinstellungen selbst anlegen, statt install.sh auszuführen: Hinterlege die Server-URL (und falls erforderlich den Token) in /opt/octoja/etc/installer.settings.json und führe das Paket dann mit dem nativen macOS-Installer (installer -pkg) aus:

sudo mkdir -p /opt/octoja/etc
cat <<'EOF' | sudo tee /opt/octoja/etc/installer.settings.json
{"octojaUrl":"https://YOUR-OCTOJA-URL","token":"YOUR-TOKEN"}
EOF

Beim Offenen Deployment lässt du den Eintrag "token" weg.

Installiere anschließend das Paket:

sudo installer -pkg octoja_<version>_<arch>.pkg -target /

Fernsupport vorbereiten

Nach einer Neuinstallation bietet der Agent dem angemeldeten Benutzer einmalig an, die fehlenden macOS-Berechtigungen für den Fernsupport einzurichten. Klicke im Fenster Berechtigungen für Remote-Support bei jeder fehlenden Berechtigung auf Einrichten und erlaube octoja Agent unter Systemeinstellungen → Datenschutz & Sicherheit die Bildschirm- & Systemaudioaufnahme für die Bildübertragung sowie Bedienungshilfen für Maus und Tastatur.

Wenn du das Fenster geschlossen hast oder später fortfahren möchtest, wähle im octoja-Symbol in der Menüleiste Berechtigungen für Remote-Support. Das Symbol erscheint nur, wenn Agent-Symbol im Traybereich anzeigen für das Gerät eingeschaltet ist. Ohne Symbol öffnet sich das Fenster erneut, sobald eine Remote-Desktop-Sitzung beginnt und noch Berechtigungen fehlen. Das Schließen des Fensters erteilt keine Berechtigungen. Eine erneute Installation auf einem bereits eingerichteten Gerät zeigt das einmalige Angebot nicht erneut.

Die Voraussetzungen und den Verbindungsaufbau findest du unter Remote-Desktop verwenden.

Agent-Status überprüfen

Der octoja Agent läuft als launchd-Dienst — das macOS-Äquivalent eines Windows-Dienstes. Öffne das Terminal (Programme → Dienstprogramme → Terminal) und führe folgenden Befehl aus:

sudo launchctl list | grep octoja

Steht in der Zeile com.octoja.agent in der ersten Spalte eine Prozess-ID, läuft der Agent; ein - bedeutet, dass er gerade nicht läuft. Die Zeile com.octoja.service-recovery zeigt meist -: Dieser Wiederherstellungsjob läuft nur alle fünf Minuten kurz und startet gestoppte Agent-Dienste wieder.

Agent-Dienst verwalten

Massenbereitstellung (MDM)

Auf macOS erfolgt die Massenbereitstellung über dein bestehendes MDM-Werkzeug. (Der in octoja integrierte Tab Automatischer Rollout deckt Intune und Gruppenrichtlinien ab und gilt für Windows.)

Wenn du Macs mit einem MDM-Tool (Mobile Device Management) wie Jamf, Mosyle oder Kandji verwaltest, kannst du die .pkg-Datei lautlos auf alle verwalteten Macs verteilen — ohne manuelle Interaktion. Verwende die oben beschriebene Sidecar-JSON-Datei-Methode, um Server-URL und Token bereitzustellen.

MDM (Mobile Device Management) ermöglicht es IT-Administratoren, Software aus der Ferne auf verwaltete Geräte zu verteilen; die für dein Tool spezifischen Schritte findest du in der Dokumentation deines MDM-Herstellers oder in Apples MDM-Übersicht.

Enrollment-Token benötigt? Siehe Enrollment-Tokens konfigurieren.

FAQ