CloakBrowser Manager Documentation

The Binary must not be used for any activity that violates applicable laws. Specifically, the following uses are expressly prohibited:

• Unauthorized access to financial, banking, healthcare, or government authentication systems.
• Credential stuffing, brute-force login attempts, or automated account creation.
• Circumventing authentication on systems you do not own or have authorization to test.
• Any activity constituting fraud, identity theft, or unauthorized data collection.

If you want to develop on the project or build your own image, you can use Docker Compose:

git clone https://github.com/CloakHQ/CloakBrowser-Manager.git
cd CloakBrowser-Manager
docker compose up --build

The Docker container binds to localhost by default. To access the manager running on a remote server from your local machine, use an SSH tunnel:

ssh -L 8080:localhost:8080 your-server

After establishing the tunnel, open http://localhost:8080 in your local browser.

The fastest way to run CloakBrowser Manager is using Docker. This command maps port 8080 and creates a persistent volume named cloakprofiles to ensure your browser profiles, cookies, and session data survive container restarts and updates.

To run the container:

docker run -p 8080:8080 -v cloakprofiles:/data cloakhq/cloakbrowser-manager

Once running, access the web interface at http://localhost:8080 to create and launch profiles.

To update to the latest version, pull the new image and restart your container. Because profiles are stored in the cloakprofiles volume, your data will persist.

docker pull cloakhq/cloakbrowser-manager
docker stop <container-id>
docker run -p 8080:8080 -v cloakprofiles:/data cloakhq/cloakbrowser-manager

The API provides a WebSocket proxy at /api/profiles/{profile_id}/vnc to allow web-based VNC clients (like noVNC) to view the browser session.

Key Features:

• Protocol Translation: It translates KasmVNC's BinaryClipboard (type 180) messages into standard RFB ServerCutText (type 3) messages so standard clients can handle clipboard data.
• RFB Filtering: It filters out unsupported RFB extension types (like EnableContinuousUpdates or QEMU-like key events) that cause KasmVNC to crash when sent by modern clients like noVNC 1.4.
• Pointer Event Rewriting: It converts standard 6-byte RFB PointerEvent messages into the 11-byte format required by KasmVNC.

You can deploy the manager service using Docker Compose. By default, the service binds to 127.0.0.1:8080 on the host, meaning it is only accessible from the local machine. Persistent data is stored in a volume mapped to ~/.cloakbrowser-manager on your host machine.

To secure the instance, you must provide an AUTH_TOKEN via an environment variable.

services:
  manager:
    build: .
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ~/.cloakbrowser-manager:/data
    environment:
      - AUTH_TOKEN=${AUTH_TOKEN:-}

For automation (e.g., using Playwright or Puppeteer), you can connect to a running profile via its CDP endpoint. The API proxies the connection to the actual Chrome instance.

1. Get Connection Info: Call GET /api/profiles/{profile_id}/cdp to get the correct URL.
2. Get Version/WebSocket URL: Call GET /api/profiles/{profile_id}/cdp/json/version. The API automatically rewrites the webSocketDebuggerUrl to point through the CloakBrowser proxy.

Example Usage (Playwright):

# Assuming the host is 'localhost:8080'
await playwright.chromium.connect_over_cdp('http://localhost:8080/api/profiles/your-profile-id/cdp')

The CloakBrowser Manager supports optional authentication via the AUTH_TOKEN environment variable.

• If AUTH_TOKEN is NOT set: All routes are open (intended for local development).
• If AUTH_TOKEN is set: All /api/* routes require authentication, except for /api/auth/* and /api/status.

Authentication Methods:

1. Bearer Token: Include Authorization: Bearer <token> in the request header.
2. Cookie: Provide the auth_token cookie.

Bypass Rule: Non-browser clients (like Playwright or Puppeteer) that do not provide an Origin header are allowed to bypass authentication even if AUTH_TOKEN is set.

Every running profile exposes a Chrome DevTools Protocol (CDP) endpoint. This allows you to connect automation tools like Playwright or Puppeteer to a running profile. A key advantage is that you can watch the automation happen live in the web GUI via the built-in noVNC viewer while the script runs.

The CDP URL can be found in the profile's toolbar by clicking the code icon.

Endpoint Format: http://localhost:8080/api/profiles/<profile-id>/cdp

from playwright.async_api import async_playwright

async with async_playwright() as pw:
    browser = await pw.chromium.connect_over_cdp(
        "http://localhost:8080/api/profiles/<profile-id>/cdp"
    )
    page = browser.contexts[0].pages[0]
    await page.goto("https://example.com")