Agent auf Windows bereitstellen

Diese Anleitung zeigt dir, wie du den octoja Agent auf einem Windows-System installierst und registrierst.

Voraussetzungen

• Ein octoja-Konto mit der Berechtigung Agent-Verwaltung — ohne sie erscheint Administration → Agent-Bereitstellung nicht in deiner Navigation
• Windows 10 / Windows Server 2016 oder neuer. Ältere Versionen bis hinunter zu Windows Server 2012 R2 funktionieren ebenfalls, benötigen aber zuvor .NET Framework 4.7.2 oder neuer — erhältlich bei Microsoft
• Microsoft Visual C++ Redistributable (x64 oder ARM64), Version 14.51.36247.0 oder neuer, auf dem Gerät. Die Schnellinstallation prüft die installierte Version und installiert oder aktualisiert sie bei Bedarf; bei Manuelle Installation und Automatischer Rollout installierst du eine unterstützte Version vor der MSI selbst
• Administratorkonto auf dem Gerät
• Internetzugang (ausgehend HTTPS auf Port 443)

Schritte

1. Navigiere in octoja zu Administration → Agent-Bereitstellung.
2. Überprüfe in Schritt 1 – Einstellungen den Bereitstellungsmodus (offenes Deployment oder Token-basiert).
3. Klicke in Schritt 2 – Plattform wählen auf Windows.
4. Wähle in Schritt 3 – Installationsmethode wählen die gewünschte Methode aus:
   • Schnellinstallation — ein einzelner PowerShell-Befehl, der die Architektur automatisch erkennt und lautlos installiert. Ideal für ein einzelnes Gerät.
   • Manuelle Installation — lade das ZIP-Archiv herunter, entpacke die MSI und installiere sie selbst mit einem Assistenten oder Silent-Flag.
   • Automatischer Rollout — generiere den Intune- oder Gruppenrichtlinien-Befehl (GPO), um auf vielen Geräten gleichzeitig bereitzustellen.
5. Kopiere den Befehl oder lade das Installationsprogramm aus dem angezeigten Bereich herunter. Lass das Fenster offen — der Befehl enthält deine individuelle Server-URL.
6. Führe den Befehl auf dem Windows-Gerät aus (siehe unten).
7. Navigiere in octoja zurück zu Geräte. Das Gerät erscheint innerhalb von Sekunden.

Schnellinstallation (empfohlen für ein einzelnes Gerät)

Kopiere den PowerShell-Befehl von der Bereitstellungsseite und füge ihn in eine PowerShell mit erhöhten Rechten auf dem Zielgerät ein.

Der PowerShell-Befehl sieht in etwa so aus:

& ([scriptblock]::Create((irm https://cdn.octoja.com/installer/install.ps1))) -OctojaUrl 'https://YOUR-OCTOJA-URL'

Falls Token-basiertes Deployment aktiviert ist, enthält der Befehl ein -Token-Argument — übernimm dieses vollständig:

& ([scriptblock]::Create((irm https://cdn.octoja.com/installer/install.ps1))) -OctojaUrl 'https://YOUR-OCTOJA-URL' -Token 'YOUR-TOKEN'

Das Skript erkennt die Gerätearchitektur (x64 oder ARM64), lädt das korrekte Paket herunter, entpackt die enthaltene MSI und führt sie lautlos aus. Es erfordert eine PowerShell-Sitzung mit Administratorrechten.

Windows Server 2016 (und ältere Windows): zuerst TLS 1.2 aktivieren. Auf diesen Systemen nutzt Windows PowerShell noch eine ältere TLS-Version, daher kann der Befehl bereits am Download-Schritt (irm https://cdn.octoja.com/installer/install.ps1) mit einem Verbindungsfehler wie „Die zugrunde liegende Verbindung wurde geschlossen: Unbekannter Fehler beim Empfangen.“ scheitern — bevor die eingebaute TLS-Anhebung des Installationsprogramms greifen kann. Aktiviere in derselben PowerShell-Sitzung mit erhöhten Rechten TLS 1.2 und führe den octoja-Befehl dann erneut aus:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Ein Zertifikatsvertrauensfehler ist etwas anderes. Endet Resolve installer URL mit „Für den geschützten SSL/TLS-Kanal konnte keine Vertrauensstellung hergestellt werden“, hilft ein Wechsel auf TLS 1.2 nicht. Der Startbefehl lädt das Skript von cdn.octoja.com; nach dem Start fragt das Skript deine octoja-Instanz nach der Installer-URL und lädt das Paket anschließend aus dem CDN. Eine Firewall oder ein Proxy mit SSL-/TLS-Deep-Inspection kann das Zertifikat beider Ziele durch ein Zertifikat der eigenen Zertifizierungsstelle ersetzen. Windows lehnt dieses Zertifikat ab, wenn es der Zertifizierungsstelle auf dem Gerät nicht vertraut.

Bitte deinen Netzwerkadministrator, sowohl die URL deiner octoja-Instanz als auch cdn.octoja.com von SSL-/TLS-Deep-Inspection auszunehmen. Öffne auf dem betroffenen Gerät beide Adressen im Browser und prüfe im Zertifikat den Aussteller. Gehört der Aussteller zu deiner Firewall, deinem Proxy oder deiner Organisation statt zur öffentlichen Zertifizierungsstelle der Website, wird die Verbindung per Deep Inspection untersucht.

Prüfe für grundlegende DNS- und Porttests beide Ziele. Ersetze https://YOUR-OCTOJA-URL durch die vollständige URL deiner Instanz. Diese Tests prüfen nicht die Zertifikatsvertrauensstellung:

$instanceHost = ([Uri]'https://YOUR-OCTOJA-URL').Host
Test-NetConnection $instanceHost -Port 443
Resolve-DnsName $instanceHost
Test-NetConnection cdn.octoja.com -Port 443
Resolve-DnsName cdn.octoja.com

Manuelle Installation (MSI)

Vor dem Ausführen der MSI: Stelle sicher, dass das Microsoft Visual C++ Redistributable (x64 oder ARM64) auf dem Gerät installiert ist. Die Schnellinstallation ergänzt es für dich; die MSI setzt voraus, dass es bereits vorhanden ist.

Wähle auf der Bereitstellungsseite Manuelle Installation aus, um die Schaltfläche Download x64 / Download ARM64 zu sehen. Der Download ist ein ZIP-Archiv — entpacke es zuerst und führe dann die enthaltene MSI (octoja.Launcher.<version>.<arch>.msi) mit msiexec aus:

msiexec /i octoja.Launcher.<version>.<arch>.msi OCTOJA_URL="https://YOUR-OCTOJA-URL"

Hänge /qn für lautlose Installation ohne Benutzeroberfläche an:

msiexec /i octoja.Launcher.<version>.<arch>.msi OCTOJA_URL="https://YOUR-OCTOJA-URL" /qn

Falls ein Enrollment-Token erforderlich ist, füge TOKEN="..." hinzu:

msiexec /i octoja.Launcher.<version>.<arch>.msi OCTOJA_URL="https://YOUR-OCTOJA-URL" TOKEN="YOUR-TOKEN" /qn

Automatischer Rollout (Intune / Gruppenrichtlinie)

Die Karte Automatischer Rollout führt dich durch jedes Bereitstellungstool. Die MSI selbst stammt aus dem Download der Manuellen Installation — entpacke sie zuerst aus dem ZIP-Archiv.

Per Gruppenrichtlinie ausrollen

Für einen Rollout per Gruppenrichtlinie erstellt octoja eine fertige Windows-Installer-Transform-Datei (benannt wie octoja.Launcher.<version>.mst), die deine Server-URL und das Enrollment-Token bereits enthält. Du setzt keine MSI-Eigenschaften mehr von Hand — die Transform-Datei setzt dieselben Eigenschaften OCTOJA_URL und TOKEN, die auch der manuelle msiexec-Befehl setzen würde. Folge diesen Schritten:

1. Wähle auf der Karte Automatischer Rollout die Registerkarte Gruppenrichtlinie (GPO) und klicke auf Transform (.mst) herunterladen. Lade die Datei nach einem Token-Wechsel erneut herunter, damit sie das neue Token enthält.
2. Lege den MSI-Installer und die .mst-Transform-Datei auf einer Netzwerkfreigabe ab (nutze UNC-Pfade wie \\Server\Freigabe\…). Erteile Domänencomputer Leserechte auf Freigabe und Dateien — die Installation läuft unter dem Computerkonto, nicht unter deinem Benutzerkonto.
3. Füge die MSI in einem GPO unter Computerkonfiguration → Softwareinstallation mit der Bereitstellungsmethode Erweitert hinzu und hänge die .mst-Datei auf der Registerkarte Änderungen an. Die Konsolenschritte beschreibt Microsofts Anleitung zur Softwareinstallation per Gruppenrichtlinie. Der Agent wird beim nächsten Start der Computer installiert.
4. Füge Domänencomputer zur Sicherheitsfilterung der GPO hinzu und verknüpfe die GPO mit der Organisationseinheit der Zielcomputer.

Sidecar-JSON-Alternative für die manuelle Installation. Anstatt URL und Token auf der msiexec-Befehlszeile zu übergeben, kannst du eine Einstellungsdatei neben der MSI ablegen. Erstelle dazu installer.settings.json im selben Ordner wie die MSI:

{
  "octojaUrl": "https://YOUR-OCTOJA-URL",
  "token": "YOUR-TOKEN"
}

Führe dann msiexec /i octoja.Launcher.<version>.<arch>.msi /qn ohne zusätzliche Eigenschaften aus — das Installationsprogramm liest die JSON-Datei automatisch. Diese Fußnote erscheint auch im Schritt „Manuelle Installation“ des Bereitstellungsassistenten.

Parameterreferenz

Installation überprüfen

1. Stelle in der Windows-Konsole Dienste sicher, dass beide Agent-Dienste Wird ausgeführt sind: Octoja Agent (Octoja.Agent) und Octoja Launcher (Octoja.Launcher).
2. Navigiere in octoja zu Geräte — das Gerät erscheint innerhalb von Sekunden nach Abschluss der Installation.

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