Headless: Browser ohne Fenster steuern

Führe Browserprofile ohne sichtbares Browserfenster aus. Nutze Local API, MCP oder einen RPA-Ablauf; die TabGecko-Desktop-App muss weiterlaufen und angemeldet sein.

Was läuft ohne Fenster?#

Anwendungsfall	Konfiguration
Vorhandenes Chromium- oder Firefox-Profil	`POST /api/v1/profiles/{id}/start` · `headless: true`
Temporäre Browsersitzung	`POST /api/v1/runtime/once` · `headless: true`
RPA-Ablauf	`headless: true` in der Ablaufdefinition
MCP-Client	Verwendet die Profilkonfiguration und dieselbe lokale Browserlaufzeit.

Headless bezieht sich auf das Browserfenster, nicht auf einen gehosteten Cloud-Dienst oder eine getrennte Desktop-Anmeldung ohne Oberfläche. Installiere zuerst den benötigten Kern und halte das Desktop-Konto verbunden. Die Anmeldung auf der Website startet keine Local API.

Vorhandenes Profil verwenden#

Starte ein vorhandenes Chromium- oder Firefox-Profil mit headless:true im Startkörper. Das gilt nur für diese Sitzung und erhält die gespeicherten Startargumente. Prüfe zuerst das installierte Schema: Ältere Clients benötigen für diese Option ein Update.

POST /api/v1/profiles/{id}/start

{"headless":true}

Node.js CLI

node tabgecko.mjs request POST /api/v1/profiles/PROFILE_ID/start headless.json
node tabgecko.mjs request GET /api/v1/profiles/PROFILE_ID/runtime
node tabgecko.mjs stop PROFILE_ID

Speichere das JSON als headless.json und ersetze PROFILE_ID durch die tatsächliche UUID. Starten und Stoppen benötigen runtime:control. Lasse automation aktiviert; automation:false lässt sich nicht mit Headless kombinieren. Der Sammelstart akzeptiert ebenfalls headless:true.

Temporäre Headless-Sitzung starten#

Diese Anfrage erstellt ein temporäres Profil und startet dessen Browser. Sie benötigt profiles:write und runtime:control sowie die entsprechenden Kontorechte. Verwende sie nur für entbehrliche Daten: Die Sitzung wird bei Ablauf oder bei aktiviertem auto_close nach dem Schließen bereinigt.

POST /api/v1/runtime/once

{
  "profile": {
    "name": "Headless example",
    "engine": "chromium"
  },
  "headless": true,
  "duration_seconds": 300,
  "auto_close": true
}

Node.js CLI

node tabgecko.mjs request POST /api/v1/runtime/once temporary.json
node tabgecko.mjs request GET /api/v1/runtime/once
node tabgecko.mjs request DELETE /api/v1/runtime/once/SESSION_ID

Speichere die Nutzdaten als temporary.json. Verwende die zurückgegebene id als SESSION_ID, nicht profile_id. Eine temporäre Sitzung gehört zu ihrem lokalen API-Token; verwende dasselbe Token zum Prüfen oder Beenden.

RPA und MCP#

Setze bei einem RPA-Ablauf headless:true auf der obersten Ebene der Ablaufdefinition und prüfe das Laufergebnis. Ein vom Server angenommener Ablauf ist noch nicht zwangsläufig abgeschlossen. MCP-Profilstarts akzeptieren body.headless:true ohne Änderung des gespeicherten Profils. Ermittle die genauen Werkzeuge und Schemas über tools/list, statt Parameter zu erfinden.

Anleitung für RPA-Abläufe · MCP verbinden

Ergebnis und Grenzen prüfen#

Prüfe die Runtime-Antwort und den Sitzungsendpunkt. Ein Startfehler, fehlender Kern oder getrenntes Konto bedeutet keine laufende Headless-Sitzung.
Seitenautomatisierung ist über unterstützte Browser-APIs verfügbar. Native Betriebssystemdialoge und Aktionen, die ein sichtbares Fenster benötigen, sind nicht mit Seitenautomatisierung gleichzusetzen.
Die Local API lauscht auf Loopback. Entfernte Clients benötigen eine unterstützte lokale Verbindung; das Öffnen dieser Dokumentation stellt keine entfernte API bereit.
Für eine sichtbare Sitzung das Profil stoppen und mit headless:false starten. Gespeicherte Startargumente bleiben unverändert.

Verbindungs- und Startfehler prüfen