Installation für IT-Dienstleister

Diese Seite richtet sich an IT-Dienstleister und Systemhäuser, die AnnexFlow bei mehreren Kunden betreiben. Sie beschreibt den technischen Weg, nicht den kaufmännischen. Was heute noch nicht von allein geht, ist als solches gekennzeichnet — inklusive der Stelle, an der es klemmt.

1. Was wird wo installiert?

AnnexFlow besteht aus drei Teilen. Nur zwei davon installierst Du überhaupt.

Server — nichts zu installieren

Die Steuerungsebene läuft gehostet auf annexflow.com. Mandanten, Benutzer, Agenten, Aufgaben, Abrechnung: alles serverseitig. Es gibt keine On-Premise-Installation des Servers.

Integrationsknoten — ein Mac je Kunde

Der Knoten (im Code und in älteren Texten „Proxy") führt aus, was der Server plant: Zeitpläne, Auslöser aus Mail und Nachrichten, Werkzeugaufrufe in den Systemen des Kunden. Er ist optional — und pro Kunde brauchst Du genau einen, nicht einen pro Arbeitsplatz.

Client — je Arbeitsplatz

Die Mac-App für den einzelnen Mitarbeiter, dazu die iOS-App aus dem App Store. Beides bezieht der Kunde selbst über /download; dort stehen auch die Systemvoraussetzungen je Programm.

Ohne Knoten arbeitet der Kunde vollwertig

Anmelden, Projekte, Aufgaben, Agenten-Chat: alles läuft ohne Knoten. Was ohne ihn stillsteht, ist das Selbsttätige — Zeitpläne, Auslöser aus Mail und Nachrichten, Werkzeugausführung und die Abnahme von Aufträgen durch den Lead-Agenten. Der Server plant, der Knoten führt aus. Für einen Kunden, der AnnexFlow nur als Oberfläche nutzt, ist der Knoten überflüssig.

2. Voraussetzungen des Knotens

Gerät

macOS 13 (Ventura) oder neuer. Das ausgelieferte Paket enthält eine grafische Hülle, die macOS 13 verlangt. Der eigentliche Dienst darunter ist reines Rust und ab macOS 11 (Big Sur) gebaut — siehe die Einschränkung weiter unten.
Apple Silicon (M1 oder neuer). Die veröffentlichten Stände sind reines arm64. Ein alter Intel-Mac als Knoten funktioniert mit dem öffentlichen Download nicht.
Der Rechner muss durchlaufen. Ruhezustand in den Energie-Einstellungen abschalten. Ein schlafender Knoten verpasst jeden Zeitplan, ohne dass irgendwo ein Fehler erscheint.
Eine offene Benutzersitzung. Der Knoten startet als LaunchAgent in der Sitzung eines angemeldeten Benutzers — der Grund dafür steht in Abschnitt 4. Ein Mac, der nach dem Neustart am Anmeldefenster stehen bleibt, startet den Knoten nicht. Für unbeaufsichtigte Knoten heißt das: automatische Anmeldung einrichten.

Netz

Ausgehend HTTPS (443) zu annexflow.com. Mehr braucht der Knoten nicht, um sich anzumelden und Aufträge abzuholen. Er meldet sich selbst beim Server — es ist keine eingehende Portfreigabe und kein VPN nötig.
Lokal: Unix-Socket unter ~/.annexflow/proxy.sock. Für Clients im selben Netz lauscht der Knoten zusätzlich auf TCP 15443. Dieser Port gehört ins lokale Netz und nicht ins Internet.
Wo der Knoten Kundensysteme erreicht (Exchange, Nextcloud, DATEV, Zabbix …), gelten deren eigene Freigaben. Der Knoten steht dafür bewusst beim Kunden und nicht in unserer Cloud.

Geht heute nicht: Knoten auf macOS 11/12

Der Dienst allein läuft ab macOS 11, und für alte Kunden-Macs gibt es ein Paket ohne grafische Hülle. Dieses Paket steht nicht zum öffentlichen Download — es wird auf Anfrage gebaut und ausgeliefert (mail@annexflow.com). Wer heute über /download geht, braucht macOS 13 und Apple Silicon.

3. Knoten installieren und koppeln

3.1 Paket beziehen und prüfen

Der Integrationsknoten steht als notariertes DMG auf /download. Prüfsumme gegen die Angabe auf der Seite halten — der Download-Knopf und die SHA-256-Summe stammen aus derselben Quelle wie die Selbstaktualisierung der Programme:

bash

shasum -a 256 ~/Downloads/AnnexFlow-Proxy-<version>.dmg
spctl -a -vvv -t open --context context:primary-signature ~/Downloads/AnnexFlow-Proxy-<version>.dmg
# erwartet: accepted / source=Notarized Developer ID
#           origin=Developer ID Application: ma-kom agentur UG (haftungsbeschraenkt) (RKFZGY3XY2)

DMG öffnen, AnnexFlow-Proxy.app nach /Applications ziehen, einmal starten. Der Startvorgang legt den LaunchAgent an (~/Library/LaunchAgents/com.annexflow.proxy.plist) und startet den Dienst.

3.2 Kopplungs-Token erzeugen

Im Admin-Cockpit unter Systemknoten → Proxy hinzufügen, oder direkt über die API — der Weg, den Du für mehrere Kunden brauchst:

bash

curl -sS -X POST https://annexflow.com/api/v1/admin/pairing-tokens \
  -H "Authorization: Bearer $ANNEXFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"proxy","tenant_id":123,"default_device_name":"Knoten Musterbau"}'

Die Antwort enthält den Token, die Kopplungsdaten (manual_payload) und einen Prüf-Einzeiler. Der Token verfällt nach 30 Minuten und lässt sich genau einmal einlösen.

3.3 Der Einzeiler prüft — er installiert nichts

bash

curl -fsSL https://annexflow.com/install/<token>.sh | bash

Dieser Befehl lädt keine App herunter

Er prüft den Kopplungs-Token gegen den Server und gibt die Daten aus, die der Knoten braucht: Server-URL, Partner-Kennung, Company-Kennung, Kopplungs-Token. Mehr tut er nicht — deshalb heißt er in der API seit dem 03.09. pruef_einzeiler und trägt das Feld installiert: false. Die alten Namen (install_url, install_oneliner) stehen nur noch da, damit bestehende Aufrufer nicht brechen. Die Installation des DMG bleibt Handarbeit (Abschnitt 3.1).

3.4 Daten in den Knoten eintragen

Die vier Werte aus dem Prüflauf setzt Du als Umgebung des Dienstes — entweder in~/.annexflow/keys/release.env oder im BlockEnvironmentVariables des LaunchAgent:

bash

ANNEXFLOW_SERVER_BASE_URL=https://annexflow.com
ANNEXFLOW_PROXY_TOKEN=<token>
ANNEXFLOW_PARTNER_SLUG=<partner>
ANNEXFLOW_TENANT_SLUG=<company>

Danach neu starten und gegenprüfen, dass der Knoten antwortet:

bash

launchctl bootout gui/$(id -u)/com.annexflow.proxy 2>/dev/null
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.annexflow.proxy.plist
printf '%s\n' '{"jsonrpc":"2.0","method":"agent.list","params":{},"id":1}' \
  | nc -U ~/.annexflow/proxy.sock

Im Admin-Cockpit erscheint der Knoten danach mit Herzschlag. Fehlt er, fehlen fast immer die vier Werte oben — der Dienst läuft dann trotzdem und meldet sich nur nicht an.

3.5 Verantwortlichen Benutzer setzen

Geht heute nur über einen Wartungsbefehl

Jeder Knoten braucht einen verantwortlichen Benutzer; ohne ihn bleibt der Live-Kontext ohne Benutzer und persönliche Agenten erreichen den Knoten nicht. Eine Oberfläche dafür gibt es heute nicht — die Zuweisung läuft über einen Wartungsbefehl auf unserer Seite. Melde den Knoten mit dem gewünschten Benutzer an mail@annexflow.com, bis der Schalter im Cockpit steht.

4. Der unbeaufsichtigte Knoten

Beim Kunden sitzt niemand vor dem Knoten. Das ist keine Eigenschaft der Umgebung, sondern der Zweck des Geräts — und der Abschnitt, an dem die meiste Zeit verloren geht, wenn man ihn überspringt.

4.1 Der Geheimspeicher darf nicht die Keychain sein

Am 03.09.2026 hing ein Knoten eine Stunde lang stumm. Der Prozess lief, launchd meldete running, das Protokoll endete mitten im Start — und der Port war nicht belegt. Die Ursache: Die macOS-Keychain wartete auf einen Bestätigungsdialog, den auf einem unbeaufsichtigten Rechner niemand sieht.

Ein Geheimspeicher, der auf eine Antwort wartet, ist kein Schutz, sondern ein Totalausfall

Und einer, den keine Fehlermeldung ankündigt: Der Knoten stürzt nicht ab, er hängt. Ein Neustart hilft nicht, weil der Dialog beim nächsten Start wieder erscheint.

Seit dem 03.09. ist deshalb der Dateispeicher die Vorgabe — eine Datei mit Rechten 0600 und abgeleitetem Hauptschlüssel. Du musst dafür nichts setzen. Wer die Keychain will (etwa auf einem Knoten mit dauerhaft angemeldetem Benutzer), setzt sie ausdrücklich:

bash

ANNEXFLOW_SECRET_STORE=keychain   # nur mit angemeldetem Benutzer am Gerät

Auch dann prüft der Knoten vorher mit einer Frist von zwei Sekunden, ob die Keychain überhaupt antwortet, und nimmt sonst die Datei: Ein Knoten, der nicht startet, schützt niemanden.

Geht heute nicht: der veröffentlichte Knoten kennt diese Umstellung noch nicht

Der aktuell über /download beziehbare Stand des Integrationsknotens stammt vom 22.08.2026 und enthält die Umstellung vom 03.09. noch nicht — im ausgelieferten Binär kommt ANNEXFLOW_SECRET_STORE nicht vor (nachgemessen am Paket selbst). Bis der nächste Stand veröffentlicht ist, gilt für diesen Download: Er kann beim ersten Schreiben eines Geheimnisses auf einen Keychain-Dialog laufen und dort hängen bleiben. Auf einem Knoten ohne Menschen davor deshalb entweder auf den nächsten Stand warten oder das Paket bei uns anfordern.

4.2 LaunchAgent, nicht LaunchDaemon

Der Knoten gehört in die Sitzung eines Benutzers (~/Library/LaunchAgents, gestartet mit launchctl bootstrap gui/$(id -u) …), nicht nach /Library/LaunchDaemons. Das ist keine Geschmacksfrage:

Startet launchd den Dienst als systemweiten Daemon, ist er sein eigenerverantwortlicher Prozess. macOS führt seine Datenschutz-Rechte dann unter der Kennung des Dienst-Binärs — nicht unter der der App. Ein Häkchen, das jemand in den Systemeinstellungen bei „AnnexFlow Proxy" setzt, gilt für die Hülle und erreicht den Dienst nicht. Genau daran ist am 13.08. ein ganzer Arbeitstag verloren gegangen.
Ohne Benutzersitzung gibt es außerdem keinen Zugriff auf die Kalender-, Kontakt- und Mail-Daten, mit denen der Knoten arbeiten soll.

Der Preis dafür steht in Abschnitt 2: Der Mac braucht eine offene Sitzung, also automatische Anmeldung, und darf nicht schlafen.

4.3 Rechte per Profil statt per Dialog

Sechs macOS-Rechte muss der Knoten haben (Bedienungshilfen, Festplattenvollzugriff, Kontakte, Kalender, Erinnerungen, Steuerung anderer Programme). Auf einem Gerät ohne Menschen davor sind sechs Dialoge kein Weg. Dafür gibt es ein PPPC-Profil, das alle sechs in einem Schritt erteilt — und, entscheidend, für beide Kennungen: die der App-Hülle und die des Dienstes darin.

bash

curl -sS -H "Authorization: Bearer $ANNEXFLOW_TOKEN" \
  -o AnnexFlow-Proxy-PPPC.mobileconfig \
  "https://annexflow.com/api/v1/admin/nodes/proxy/<knoten-id>/pppc-profile?team_id=RKFZGY3XY2"

Das Profil lädst Du in Dein MDM und weist es dem Gerät zu — es gilt dann sofort, ohne Klick am Gerät. Ohne MDM: Profil auf den Knoten kopieren, öffnen, und unter Systemeinstellungen › Allgemein › Geräteverwaltung bestätigen. Ein Vorgang statt sechs Dialoge.

Geht heute nicht: Profil vor der Kopplung

Das Profil wird für einen konkreten, bereits registrierten Knoten erzeugt — die Knoten-ID steckt im Aufruf. Ein allgemeines Profil, das Du vorab in Dein MDM legen und auf vierzig Geräte ausrollen könntest, bevor der erste Knoten existiert, gibt es nicht. Reihenfolge heute also: koppeln, dann Profil ziehen, dann zuweisen.

Zwei Rechte kann auch das Profil nicht erteilen, weil macOS dafür keinen Profilweg anbietet: lokales Netzwerk sowie Kamera und Fotos. Beide kommen ausschließlich als Dialog beim ersten Zugriff. Wenn der Knoten Geräte im Kundennetz ansprechen soll, muss diesen einen Dialog jemand am Gerät bestätigen.

4.4 Rechte prüfen, ohne Dialoge auszulösen

bash

~/.annexflow/dienst/annexflow-proxy-service --berechtigungen
~/.annexflow/dienst/annexflow-proxy-service --berechtigungen --anfordern

Der erste Aufruf fragt nichts — er berichtet nur, was bei echten Aufrufen beobachtet wurde. Der zweite löst Systemdialoge absichtlich aus und gehört deshalb an einen Zeitpunkt, an dem jemand zusieht. Ein Dialog, der unerwartet während eines Auftrags aufgeht, scheitert nicht sichtbar — er hängt.

Nicht über SSH messen

--berechtigungen misst die Rechte des aufrufenden Prozesses. Über SSH ist das der SSH-Dienst, nicht der Knoten. Das Ergebnis ist dann richtig gemessen und trotzdem falsch verstanden.

5. Rollout für vierzig Kunden

Ehrliche Antwort vorweg: Ein vollautomatischer Rollout existiert heute nicht. Skriptbar ist der Server-Teil, Handarbeit bleibt der Teil am Gerät. So sieht die Trennung aus:

Skriptbar (API, ein Token, eine Schleife)

Mandant je Kunde anlegen — POST /api/v1/tenants/from-template. Nur dieser Weg legt auch das Agenten-Team an; die Selbstregistrierung und der Rollout-Tab tun das nicht.
Benutzer anlegen je Mandant, inklusive Willkommensmail.
Kopplungs-Token erzeugen — POST /api/v1/admin/pairing-tokens, siehe 3.2. Beachte die 30-Minuten-Frist: erzeuge sie beim Ausrollen, nicht auf Vorrat.
PPPC-Profil ziehen je gekoppeltem Knoten und ins MDM laden, siehe 4.3.
Zustand prüfen — Knotenliste, Herzschlag und Berechtigungs-Inventar je Knoten stehen als Admin-Endpunkte bereit.

Handarbeit am Gerät

DMG installieren. Es gibt keinen stillen Installer und keinen Einzeiler, der die App holt (siehe 3.3). Wer ein MDM betreibt, packt das notarisierte DMG selbst in ein Paket und verteilt es darüber — das ist heute der einzige Weg zu einer unbeaufsichtigten Installation.
Vier Umgebungswerte setzen (3.4). Über MDM-Skript oder Fernwartung automatisierbar, aber nicht Teil des Produkts.
Automatische Anmeldung und Ruhezustand je Gerät einstellen.
Der eine Dialog fürs lokale Netzwerk, falls der Knoten Geräte im Kundennetz erreichen soll (4.3).

Geht heute nicht: vierzig Kunden-Companies im Partner-Tarif

Der Partner-Tarif enthält eine Kunden-Company. Jede weitere wird einzeln freigeschaltet — über das Add-on „Weitere Kunden-Company" oder eine Betreiber-Freigabe. Wer mit vierzig Kunden startet, klärt das Kontingent vor dem ersten Rollout, sonst bricht der einundvierzigste Anlagelauf mitten im Kundentermin ab. Und: Für Partner Pro gibt es heute keinen Selbstbedienungs-Kauf — die Freischaltung läuft über mail@annexflow.com.

6. Was heute nicht geht — auf einen Blick

Kein Auto-Installer. Der Einzeiler prüft nur den Token. Die App kommt per DMG oder über Dein MDM.
Kein Knoten-Paket für macOS 11/12 zum Download und keine Intel-Fassung — beides auf Anfrage.
Der veröffentlichte Knoten (Stand 22.08.) kennt die Umstellung des Geheimspeichers vom 03.09. noch nicht und kann auf einem unbeaufsichtigten Gerät auf einen Keychain-Dialog laufen.
Kein allgemeines PPPC-Profil vor der Kopplung — es wird je registriertem Knoten erzeugt.
Lokales Netzwerk, Kamera und Fotos lassen sich per Profil nicht erteilen, nur per Dialog am Gerät.
Verantwortlicher Benutzer eines Knotens nur über einen Wartungsbefehl, nicht über die Oberfläche.
Eine Kunden-Company je Partner-Tarif; weitere brauchen eine Freischaltung.

Fragen zu einem konkreten Rollout, zum Paket für ältere Macs oder zum Kontingent: mail@annexflow.com. Weiter zur Branchen-Sicht: IT-Dienstleistung & Managed Services.