Skip to content

README.md

Latest commit

 

History

History
215 lines (150 loc) · 8.17 KB

README.md

File metadata and controls

215 lines (150 loc) · 8.17 KB
Raw

CloakBrowser

Browser Profile Manager for CloakBrowser

Create, manage, and launch isolated browser profiles with unique fingerprints.
Free, self-hosted alternative to Multilogin, GoLogin, and AdsPower.

Stars Docker Pulls License

CloakBrowser Manager — Browser View
CloakBrowser Manager — Profile Settings

Each profile is an isolated CloakBrowser instance with its own fingerprint, proxy, cookies, and session data. Profiles persist across restarts. Windows and macOS launch browsers directly in native desktop windows; Linux keeps the Docker/KasmVNC server experience.

Windows and macOS

Clone the repository, then start the platform launcher:

Windows: run-windows.bat
macOS:   ./run-macos.sh

The first run creates a local Python environment, installs dependencies, builds the React UI, starts Manager on 127.0.0.1:8080, and opens it in your default browser. Profiles are stored in %LOCALAPPDATA%\CloakBrowser Manager on Windows and ~/Library/Application Support/CloakBrowser Manager on macOS.

Linux server

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

Or build from source:

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

Open http://localhost:8080, create a profile, and click Launch.

Early alpha — this project is under active development. Expect bugs. If you find one, please open an issue.

Why Not Just Use a VPN?

A VPN only changes your IP. Incognito only clears cookies. Chrome profiles share the same hardware fingerprint underneath. Platforms use 50+ signals to link your accounts — canvas, WebGL, audio, GPU, fonts, screen size, timezone.

Each CloakBrowser profile generates a completely different device identity. To the website, each profile looks like a different computer.

Solution What it changes Accounts linked?
VPN IP address only Yes — same fingerprint
Incognito Clears cookies Yes — same fingerprint
Chrome profiles Separate bookmarks/cookies Yes — same hardware fingerprint
CloakBrowser Everything — full device identity per profile No

Features

  • Profile management — create, edit, delete browser profiles with unique fingerprints
  • Per-profile settings — fingerprint seed, proxy, timezone, locale, user agent, screen size, platform
  • One-click launch/stop — each profile runs as an isolated CloakBrowser instance
  • Session persistence — cookies, localStorage, and cache survive browser restarts
  • Platform-native browsing — Windows and macOS profiles open in normal desktop windows
  • Linux server viewing — interact with Docker-launched browsers through KasmVNC in the web GUI
  • Playwright/Puppeteer API — connect to any running profile programmatically via CDP, while still watching it live in the browser
  • Optional authentication — protect the web UI and API with a single token, or run wide open locally
  • Powered by CloakBrowser — 32 source-level C++ patches, passes Cloudflare Turnstile, 0.9 reCAPTCHA v3 score

Stack

  • Backend: FastAPI (Python)
  • Frontend: React + Tailwind CSS
  • Browser viewer: native windows on Windows/macOS; noVNC/KasmVNC on Linux Docker
  • Database: SQLite
  • Browser engine: CloakBrowser (stealth Chromium binary)

Development

Native backend

python -m venv .venv && source .venv/bin/activate
pip install -r backend/requirements.txt
uvicorn backend.main:app --reload --host 127.0.0.1 --port 8080

Frontend

cd frontend
npm install
npm run dev

Docker

docker compose up --build

Requirements

  • Windows or macOS native: Python 3.10+, Node.js 18+
  • Linux server: Docker 20.10+
  • ~2 GB disk (application + browser binary)
  • ~512 MB RAM per running profile

Updating

Pull the latest image and restart:

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

Your profiles and session data are stored in the cloakprofiles volume and persist across updates.

Automation API

Every running profile exposes a CDP (Chrome DevTools Protocol) endpoint. Connect Playwright or Puppeteer to automate a profile while watching it live in the browser.

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")
const { chromium } = require("playwright");

const browser = await chromium.connectOverCDP(
  "http://localhost:8080/api/profiles/<profile-id>/cdp"
);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://example.com");

The CDP URL is available from the running-profile view. The same browser session is accessible through its native window on Windows/macOS or through VNC on Linux Docker, and programmatically through the API on every platform.

Remote Access

The container binds to localhost only. To access from a remote server:

ssh -L 8080:localhost:8080 your-server

Then open http://localhost:8080.

Authentication

By default, there is no authentication (ideal for local use). To protect the web UI and API when hosting on a network, set the AUTH_TOKEN environment variable:

docker run -p 8080:8080 -v cloakprofiles:/data -e AUTH_TOKEN=your-secret-token cloakhq/cloakbrowser-manager

Or in docker-compose.yml:

environment:
  - AUTH_TOKEN=your-secret-token

When AUTH_TOKEN is set:

  • The web UI shows a login page. Enter the token to unlock.
  • API consumers pass the token via Authorization: Bearer <token> header.
  • VNC WebSocket connections are authenticated via the login cookie.
  • The /api/status endpoint remains unauthenticated (for Docker healthcheck).

Note: The auth token is transmitted in cleartext over HTTP. If you expose the Manager to the internet, put it behind a reverse proxy with HTTPS (Caddy, nginx, Traefik).

License

  • This application (GUI source code) — MIT. See LICENSE.
  • CloakBrowser binary (compiled Chromium) — free to use, no redistribution. See BINARY-LICENSE.md.

The GUI application requires the CloakBrowser Chromium binary to function. The binary is automatically downloaded on first launch and is governed by its own license terms. If you fork or redistribute this application, your users must comply with the CloakBrowser Binary License.

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

Contributors

Links