Docker¶
Das veröffentlichte Bild zeigt die empfohlene Laufzeit für eine wiederholbare Nutzung von MCP.
Eine kurze Anleitung für einen bereits laufenden HTTP-Server hinter TLS und Authentifizierung bietet das Docker-Streamable-HTTP-Rezept für Reverse Proxies.
Ausführen¶
Artefakte werden im Container unter /data gespeichert. Mounten Sie diesen Pfad, um Screenshots, Snapshots, Downloads und Netzwerkausgaben zu speichern.
Das Image führt Tini bereits als PID 1 und Subreaper aus, daher benötigen normale Befehle keinen zusätzlichen Docker-init-Prozess.
Die gleichen Release-Tags werden auf Docker Hub als swimmwatch/cloakbrowser-mcp und auf GHCR als ghcr.io/swimmwatch/cloakbrowser-mcp.
Sitzungen mit grafischer Oberfläche und virtuelle Anzeige¶
Das Image verwendet standardmäßig PLAYWRIGHT_MCP_HEADLESS=true; Headless-Sitzungen starten Xvfb nicht. Fordert eine Sitzung headless: false an, startet der Launcher bei Bedarf eine containerinterne Xvfb-Anzeige, wartet auf deren Betriebsbereitschaft und hält sie bis zum Containerende aktiv. Gleichzeitige HTTP-Sitzungen mit grafischer Oberfläche teilen diese Anzeige, während ihre Playwright-Browserkontexte, Seiten, Profile und Artefakte weiterhin isoliert bleiben.
Setzen Sie für eine stdio-Sitzung mit grafischer Oberfläche die übliche Playwright-MCP-Variable:
docker run --rm -i \
-e PLAYWRIGHT_MCP_HEADLESS=false \
-v "$PWD/artifacts:/data" \
swimmwatch/cloakbrowser-mcp:latest
Dies ist weder ein sichtbarer Desktop noch ein GUI-Streamingdienst: Das Image bietet kein VNC, noVNC, RDP, keinen Zugriff auf Host-X11 und keine Anzeigeaufzeichnung. Behandeln Sie nativen X11-Fokus, Zwischenablage und Anzeigeaufzeichnung nicht als Isolationsgrenzen zwischen Mandanten. Der Launcher stoppt die Anzeige beim Herunterfahren. Ein Startfehler oder das Ende der MCP CLI beendet den Container, statt eine weiterhin nutzbare Bridge zurückzulassen.
Auch außerhalb dieses Images benötigt ein Browser mit grafischer Oberfläche eine nutzbare Anzeigeumgebung. Setzen Sie PLAYWRIGHT_MCP_HEADLESS=true, wenn keine Anzeige verfügbar ist.
Containerzustand und eingeschränkte Laufzeit¶
Der Docker-HEALTHCHECK verwendet einen privaten Unix-Socket und prüft aktiv, ob die Ereignisschleife der MCP CLI antwortet. Wenn Xvfb gestartet wurde, prüft er auch die X11-Anzeige. Ein Headless-Container, für den nie eine Anzeige angefordert wurde, bleibt gesund. Anzeigenstart, Herunterfahren der Anzeige oder ein Anzeigenfehler führen zu einem ungesunden Zustand. Die X11-Antwortprüfung ist auf 1 Sekunde, die CLI-Antwort auf 750 Millisekunden und die private Zustandsanfrage auf 2.5 Sekunden begrenzt. Docker beendet einen einzelnen Prüfungsbefehl nach 3 Sekunden. Bei einem Docker-Intervall von 2 Sekunden und zwei Wiederholungen hängen Zustandsübergänge von der Docker-Zeitplanung ab und sind kein Verfügbarkeits-Service-Level-Ziel. Diese Prüfung ist von den öffentlichen HTTP-Endpunkten /healthz und /readyz getrennt und sendet niemals Datenverkehr über MCP-stdio. Sie belegt nicht, dass ein Browser, eine MCP-Sitzung oder eine entfernte Website nutzbar ist. Neustart und Wiederherstellung liegen beim externen Orchestrator.
Der Launcher wartet pro Kindprozess nach SIGTERM bis zu 8 Sekunden und anschließend nach SIGKILL bis zu 2 Sekunden auf dessen Ende. Das Docker-Stoppzeitlimit muss das nacheinander erfolgende Herunterfahren von CLI und Xvfb berücksichtigen. Das Image läuft als Benutzer node ohne Root-Rechte und unterstützt ein schreibgeschütztes Root-Dateisystem. Halten Sie /data für Artefakte eingehängt und stellen Sie beschreibbare temporäre Mounts für /tmp und /tmp/.X11-unix bereit, wenn Sitzungen mit grafischer Oberfläche möglich sind. Der Zustandssocket ist nur für den Eigentümer zugänglich (0600). Der containerinterne X11-Socket wird vom node-Prozess und Xvfb gemeinsam genutzt und bildet daher keine Isolationsgrenze zwischen Mandanten. Mounten Sie keinen dieser Sockets vom Host und teilen Sie sie nicht zwischen Containern.
Persistente Profile¶
Docker aktiviert standardmäßig kein persistentes Browserprofil. Verwenden Sie das vorhandene Volume /data als Persistenzwurzel, wenn Cookies, lokaler Speicher, Cache oder Erweiterungsstatus Container-Neustarts überdauern sollen:
docker run --rm -i \
-e PLAYWRIGHT_MCP_USER_DATA_DIR=/data/profiles/default \
-v "$PWD/artifacts:/data" \
swimmwatch/cloakbrowser-mcp:latest
Umgebungsvariablen innerhalb von Docker müssen Containerpfade wie /data/profiles/default verwenden, keine Hostpfade. Die Bridge erstellt fehlende Profilverzeichnisse, prüft den Schreibzugriff, schreibt den Containerpfad in die generierte Playwright-MCP-Konfiguration und sperrt ausdrücklich konfigurierte Profile. Verwenden Sie auch über Container hinweg nur einen aktiven Server pro Profil; die Grenzen der Wiederherstellung sind unter Persistentes Login-Profil beschrieben.
CloakBrowser-Lizenzcache¶
Das Image speichert CloakBrowser-Binärdateien, Lizenzstatus und Validierungscache unter /home/node/.cloakbrowser. Mounten Sie dort ein benanntes Volume, um eine kostenlose GitHub- oder Pro-Anmeldung beim Ersetzen des Containers beizubehalten:
docker volume create cloakbrowser-cache
docker run --rm -it \
--entrypoint node \
-v cloakbrowser-cache:/home/node/.cloakbrowser \
swimmwatch/cloakbrowser-mcp:latest \
/opt/cloakbrowser-mcp/node_modules/cloakbrowser/dist/cli.js login
docker run --rm -i \
-v cloakbrowser-cache:/home/node/.cloakbrowser \
-v "$PWD/artifacts:/data" \
swimmwatch/cloakbrowser-mcp:latest
Verwenden Sie dasselbe Volume mit dem vorgelagerten Befehl info oder logout, um die gespeicherte Anmeldung zu prüfen oder zu entfernen. Alternativ können Sie CLOAKBROWSER_LICENSE_KEY über die Secret-Verwaltung des Containers einspeisen. Legen Sie Lizenzschlüssel nicht in Image-Layern, versionierten Compose-Dateien oder als Buildnachweis erfassten Befehlsausgaben ab.
Benutzerdefinäre CloakBrowser-Binärdatei¶
Binden Sie eine kompatible Browser-Binärdatei in den Container ein und übergeben Sie ihren Containerpfad über --binary-path (oder CLOAKBROWSER_BINARY_PATH):
docker run --rm -i \
-v "$PWD/artifacts:/data" \
-v "$PWD/custom-chrome:/browser/chrome:ro" \
swimmwatch/cloakbrowser-mcp:latest \
--binary-path /browser/chrome
Die Datei muss ein lesbares Linux-Programm sein, das zur CPU-Architektur des Images passt; benötigte Bibliotheken müssen im Container verfügbar sein. Der Pfad gilt für alle Streamable-HTTP-Sitzungen in diesem Container; verwenden Sie getrennte Container für unterschiedliche Browser-Binärdateien.
Chrome-Erweiterungen¶
Chrome-Erweiterungen erfordern ein persistentes Profil und müssen separat gemountet werden. Verwenden Sie Containerpfade in Umgebungsvariablen, keine Hostpfade. Der Erweiterungs-Mount kann schreibgeschützt sein:
docker run --rm -i \
-e PLAYWRIGHT_MCP_USER_DATA_DIR=/data/profiles/default \
-e CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS=/extensions/my-extension \
-v "$PWD/artifacts:/data" \
-v "$PWD/extensions/my-extension:/extensions/my-extension:ro" \
swimmwatch/cloakbrowser-mcp:latest
Verwenden Sie ein JSON-Array für CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS, wenn ein Pfad Kommas enthält oder wenn mehrere Erweiterungsverzeichnisse übergeben werden. Starten Sie den Container neu, nachdem Sie Erweiterungsdateien oder Erweiterungspfade geändert haben.
Der Playwright-Extension-Verbindungsmodus unterscheidet sich vom oben gezeigten Mount einer entpackten Erweiterung. Er benötigt die offizielle Erweiterung in einem persistent Chrome/Edge profile und PLAYWRIGHT_MCP_EXTENSION_TOKEN. Mounten Sie jedes profile in einen eigenen writable path, injizieren Sie das Token über einen Secret Manager und kombinieren Sie PLAYWRIGHT_MCP_EXTENSION=true nicht mit CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS.
Streamable HTTP¶
Für die lokale Nutzung von Streamable HTTP veröffentlichen Sie den Container-Port über Loopback:
docker run --rm -p 127.0.0.1:3000:3000 \
-v "$PWD/artifacts:/data" \
swimmwatch/cloakbrowser-mcp:latest \
--transport streamable-http --http-host 0.0.0.0 --http-port 3000
curl http://127.0.0.1:3000/healthz
curl http://127.0.0.1:3000/readyz
Setzen Sie für HTTP-Sitzungen mit grafischer Oberfläche PLAYWRIGHT_MCP_HEADLESS=false im Container. Einzelne initialize-Anfragen können über die unterstützten MCP-Metadaten weiterhin den Headless-Modus wählen.
docker run --rm -p 127.0.0.1:3000:3000 \
-e PLAYWRIGHT_MCP_HEADLESS=false \
-v "$PWD/artifacts:/data" \
swimmwatch/cloakbrowser-mcp:latest \
--transport streamable-http --http-host 0.0.0.0 --http-port 3000
Für einen direkten HTTPS-Zugriff aus dem Container heraus mounten Sie Ihre Zertifikatsdateien und wählen Sie „HTTPS“ aus:
docker run --rm -p 127.0.0.1:3000:3000 \
-v "$PWD/artifacts:/data" \
-v "$PWD/certs:/certs:ro" \
swimmwatch/cloakbrowser-mcp:latest \
--transport streamable-http --http-host 0.0.0.0 --http-port 3000 \
--http-protocol https --https-cert /certs/cert.pem --https-key /certs/key.pem
Die hostseitige Bindung 127.0.0.1:3000 sorgt dafür, dass der Endpunkt lokal bleibt. Wenn Sie Streamable HTTP über eine Nicht-Loopback-Schnittstelle veröffentlichen, verwenden Sie HTTPS mit Authentifizierung oder stellen Sie den Server hinter einem vertrauenswürdigen Reverse-Proxy mit TLS-Terminierung, Authentifizierung und Netzwerkkontrollen bereit. Streamable HTTP stellt feste GET /healthz und GET /readyz-Probes auf demselben Host und Port. Wenn --http-auth-token oder CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN konfiguriert sind, benötigen die Probes denselben Authorization: Bearer ...-Header wie MCP-Anfragen. Alle HTTP-Transportflags und Umgebungsvariablen finden Sie in der generierten CLI-Referenz.
Verwaltete CDP¶
Veröffentlichen Sie den konfigurierten Managed-CDP-Bereich eins zu eins. Dieses stdio-Beispiel aktiviert eins Sitzung und hält jeden Host-Port an die Loopback-Adresse gebunden:
docker run --rm -i \
-p 127.0.0.1:9222-9231:9222-9231 \
-v "$PWD/artifacts:/data" \
swimmwatch/cloakbrowser-mcp:latest \
--cdp-enabled \
--cdp-port-range 9222-9231 \
--cdp-host 0.0.0.0 \
--cdp-allow-remote \
--cdp-advertised-host 127.0.0.1
--cdp-host 0.0.0.0 wird für Docker-Portweiterleitung benötigt, daher die explizite --cdp-allow-remote Opt-in und konkretes --cdp-advertised-host sind ebenfalls erforderlich. Weisen Sie den Bereich nicht auf andere Host-Portnummern um: Discovery-URLs enthalten die Geleaster Port und jeder veröffentlichte Port müssen eins-zu-eins zu ihrer eigenen Sitzung geleitet werden.
Für Multi-Session Streamable HTTP konfigurieren und veröffentlichen Sie den Pool, ohne das Setzen des Standardverfahren, falls Kunden sich individuell anmelden sollen:
docker run --rm \
-p 127.0.0.1:3000:3000 \
-p 127.0.0.1:9222-9231:9222-9231 \
-v "$PWD/artifacts:/data" \
swimmwatch/cloakbrowser-mcp:latest \
--transport streamable-http \
--http-host 0.0.0.0 \
--http-port 3000 \
--cdp-port-range 9222-9231 \
--cdp-host 0.0.0.0 \
--cdp-allow-remote \
--cdp-advertised-host 127.0.0.1
Eine authentifizierte initialize-Anfrage mit cdpEnabled: true-Leasing mietet eine veröffentlichte Port. Ein ausgelassener Wert übernimmt den Standard des Prozesses, während cdpEnabled: false weist ausdrücklich ab und verbraucht keinen CDP-Port. Poolerschöpfung lehnt nur einen neuen ab CDP-aktivierte Sitzung; sie verringert nicht die Kapazität für deaktivierte Sitzungen.
Lesen Sie den fähigkeitsführenden URL von cloakbrowser_bridge_info. Legen Sie ihn nicht hinein Container-Protokolle oder Gesundheitsprüfungen. Verbinden Sie sich mit einem CDP API wie chromium.connectOverCDP(); der URL ist nicht kompatibel mit Playwright chromium.connect() oder der aktuelle Open WebUI-Fluss.
--cdp-advertised-scheme https ändert veröffentlichte URLs zu https/wss, aber die Die Brücke stellt TLS für verwaltete CDP nicht bereit. Verwenden Sie einen vom Betreiber betriebenen TLS-Abschluss, der belegt denselben beworbenen Port im externen Netzwerknamensraum, bewahrt Host/Origin und leitet eins zu eins an den Klartext-Bridge-Listener weiter. Der bridge-to-Chromium Hop bleibt auch Klartext-Loopback-Verkehr.
GeoIP-Proxy-Abgleich¶
Docker verwendet dieselben Proxy- und GeoIP-Umgebungsvariablen wie npm. Aktivieren Sie die GeoIP-Proxy-Zuordnung, wenn die regionale Qualitätssicherung die Zeitzonen-, Sprach- und Lokalisierungs-Fingerabdrücke von CloakBrowser benötigt, um dem konfigurierten Proxy-Standort zu folgen:
docker run --rm -i \
-e PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \
-e CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \
-v "$PWD/artifacts:/data" \
swimmwatch/cloakbrowser-mcp:latest
Bei authentifizierten Proxys müssen Sie die Anmeldedaten in die Proxy-URL einbetten und Sonderzeichen im Benutzernamen oder Passwort prozentkodieren.
Unterstützte CloakBrowser-Binärdateien verwenden die native Inline-Proxy-Authentifizierung in der URL; ältere Binärdateien greifen auf das Playwright-Proxyobjekt zurück.
Wenn der Container „Streamable HTTP“ ausführt, können Clients über die Metadaten initialize auch unterschiedliche Proxys pro MCP-Sitzung auswählen. Siehe GeoIP-Proxy-Zuordnung für Proxy-Metadaten zur Laufzeit, Anwendungsfälle in mehreren Regionen und Einschränkungen.
Standardwerte¶
| Variable | Default |
|---|---|
PLAYWRIGHT_MCP_BROWSER_ENGINE | cloak |
PLAYWRIGHT_MCP_HEADLESS | true |
PLAYWRIGHT_MCP_OUTPUT_DIR | /data |
PLAYWRIGHT_MCP_USER_DATA_DIR | unset |
CLOAK_PLAYWRIGHT_MCP_TRANSPORT | stdio |
CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL | http |
CLOAK_PLAYWRIGHT_MCP_HTTP_HOST | 127.0.0.1 |
CLOAK_PLAYWRIGHT_MCP_HTTP_PORT | 3000 |
CLOAK_PLAYWRIGHT_MCP_HTTP_ENDPOINT | /mcp |
CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN | unset |
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_BACKEND | memory |
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_IDLE_TTL_MS | 3600000 |
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_MAX | 32 |
CLOAK_PLAYWRIGHT_MCP_LOG_LEVEL | info |
CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH | false |
CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS | unset |
CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS | unset |
CLOAK_PLAYWRIGHT_MCP_CONSOLE_FALLBACK | true |
CLOAK_PLAYWRIGHT_MCP_STEALTH_ARGS | true |
CLOAK_PLAYWRIGHT_MCP_NO_SANDBOX | true |
MCP-Client-Konfiguration¶
{
"mcpServers": {
"cloakbrowser": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v",
"/tmp/cloakbrowser-artifacts:/data",
"swimmwatch/cloakbrowser-mcp:latest"
]
}
}
}
Lokal erstellen¶
Das Dockerfile verwendet das festgelegte offizielle Playwright-MCP-Image als Laufzeitbasis, wendet während des Builds verfügbare Debian-Sicherheitsupdates an, entfernt die ungenutzte globale npm-Nutzlast aus dem Laufzeit-Image und installiert die Bridge unter /opt/cloakbrowser-mcp.
CI scannt Docker-Images vor dem Zusammenführen von Änderungen mit Trivy. Der Release-Workflow veröffentlicht SBOM und Herkunftsbescheinigungen und enthält OCI-Labels für Quelle, Revision, Version, Lizenz, Name und Digest des Basis-Images.
Weitere praktische Pfade¶
Für die Entscheidung zwischen upstream Playwright MCP und diesem Paket nutzen Sie den Vergleich. Für kurze Aufgaben nutzen Sie die Rezepte: persistentes Profil, Erweiterungen, reverse proxy, regionale QA, Claude Desktop, Codex CLI und CI-Smoke-Test.