CloakBrowser-Manager

---

Open a profile and you don't get a new tab, you get a different computer: its own browser fingerprint, GPU, screen, timezone, proxy, cookies, and history. Nothing bleeds between profiles, so your accounts never link back to each other, or to you. Close a profile and reopen it next day, it's the same person, warmed up and ready.

Windows and macOS launch browsers directly in native desktop windows; Linux keeps the Docker/KasmVNC server experience.

Windows and macOS

Download the installer from the latest release and run it:

• macOS — open the .dmg and drag CloakBrowser Manager into Applications. (Unsigned during early access — on first launch, run xattr -rc "/Applications/CloakBrowser Manager.app" in Terminal, or approve it under System Settings → Privacy & Security → Open Anyway.)
• Windows — run the setup .exe. (Unsigned during early access — if SmartScreen warns, click More info → Run anyway.)

No Python, Node, or git required. The Manager starts on 127.0.0.1:8080 and opens in your default browser. On first launch it downloads the CloakBrowser engine. Profiles are stored in %LOCALAPPDATA%\CloakBrowser Manager on Windows and ~/Library/Application Support/CloakBrowser Manager on macOS; a logs/manager.log in that folder records what happened if you need it.

Open Settings (gear icon, top right) to add your license key and pick the Stable or Preview channel.

Run from source (developers)

git clone https://github.com/CloakHQ/CloakBrowser-Manager.git
cd CloakBrowser-Manager
./run-macos.sh      # macOS  (or run-windows.bat on Windows)

This path requires Python 3.10+ and Node 24.15+; the first run creates a local Python environment, installs dependencies, and builds the React UI before starting the Manager.

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 and attach the log so we can help. On Windows/macOS it's logs/manager.log in the data folder (%LOCALAPPDATA%\CloakBrowser Manager / ~/Library/Application Support/CloakBrowser Manager); on Linux/Docker use docker logs <container>.

CloakBrowser license key

The Manager runs on the CloakBrowser engine, so it needs a key. Get a free one by email to run one profile at a time on the current build. Paid plans raise how many profiles run at the same time, from a handful to thousands.

Add your key once and every profile uses it.

Native app (Windows/macOS): open Settings (gear icon, top right), paste your key, choose the Stable or Preview channel, and Save. It applies immediately, no restart. The badge in the top bar shows which tier and binary version are active.

Docker: open Settings (gear icon, top right) the same way, paste your key, and Save. It applies immediately and is stored in the mounted /data volume, so it persists across restarts and image updates. For automated or headless setups, pass it at docker run instead:

docker run -p 127.0.0.1:8080:8080 -v cloakprofiles:/data \
  -e CLOAKBROWSER_LICENSE_KEY=cb_your_key_here \
  -e CLOAKBROWSER_RELEASE_CHANNEL=preview \
  cloakhq/cloakbrowser-manager

Run from source (or docker compose): set it in a manager-root .env:

cp .env.example .env

# .env
CLOAKBROWSER_LICENSE_KEY=cb_your_key_here
CLOAKBROWSER_RELEASE_CHANNEL=stable   # or: preview

The file is loaded automatically at startup (docker compose reads it too); restart the Manager after changing it. An environment variable overrides the in-app setting.

Why Not a Cloud Anti-Detect Browser?

The popular anti-detect browsers solve the fingerprint, then hand you a new problem: every account you own, every cookie, every session, sits on someone else's servers. And the disguise increasingly doesn't survive real detection, shortcuts in how fingerprints are faked, GPU and WebGL values that don't add up, identities that pass a test page and fail the real site.

CloakBrowser Manager runs on your own machine, and every profile inherits the CloakBrowser engine, so the identities actually hold up.

	Typical cloud anti-detect browser	CloakBrowser Manager
Pricing model	Per profile + per seat, forced up-tiering	Flat by concurrency, unlimited profiles
Where profiles live	Their cloud	Your machine
Fingerprinting	JS-injected into a stock browser	Source-level C++ patched engine
The app	Closed box	Open-source GUI (MIT)
Native desktop windows	Rare	Windows + macOS
Automation API	Add-on / higher tier	CDP built in, every profile
Cost of idle accounts	Counts against your limit	Free

Features

• Unlimited profiles, no per-profile tax — create as many identities as you want. You pay only for how many run at the same time, not how many you keep. Dormant accounts cost nothing.
• Each profile is a different machine — its own fingerprint seed, GPU family, screen, cookies, localStorage, cache, and history, persistent across restarts
• Per-profile network and locale — proxy, GeoIP, timezone, locale, and screen, per profile; timezone and language follow the proxy exit IP automatically
• Platform-aware hardware profiles — automatic Apple Silicon selection and configurable Windows GPU families, coherent within each profile
• Profile organization: create, edit, auto-launch, and delete profiles. Filter by tags or untagged profiles, with counts; selecting multiple tags matches profiles with every selected tag. Search names, proxies, and notes. Tags and notes appear together in the list.
• Configurable sidebar width: set SIDEBAR_WIDTH without rebuilding the frontend (see Runtime UI configuration).
• Duplicate with browser state — clone a profile with just its settings, or together with its cookies, logged-in sessions, and storage
• Profile files — send files to a profile and, on a Linux server, keep everything its browser downloads
• 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 through CDP while watching the same session live
• Humanized interaction — optional human-like mouse, keyboard, and scrolling behavior
• Compatibility controls — unpacked extensions, third-party-cookie support, and advanced Chromium arguments
• Clipboard sync — copy and paste between the Manager and Linux VNC browser profiles
• License and system status — see the active tier, binary version, and Windows font health in the top bar
• Optional authentication — protect the web UI and API with a single token, or run locally without authentication
• Powered by CloakBrowser — the identities don't just look different, they hold up: a source-level C++ patched Chromium engine tested against Cloudflare Turnstile, reCAPTCHA v3, FingerprintJS, and BrowserScan

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 24.15+
• Linux server: Docker 20.10+
• ~2 GB disk (application + browser binary)
• ~512 MB RAM per running profile

Updating

Windows and macOS

Pull the latest source and run the platform launcher again. It installs changed dependencies and rebuilds the interface automatically.

git pull

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

Linux server

Pull the latest image and recreate the container:

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

Profiles and session data remain in the native application-data directory or the cloakprofiles Docker volume 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.

Profile files

A profile can exchange files with the outside world. This matters most under Docker, where the browser cannot see your filesystem: a file you want to upload to a website is not reachable from the guest's file dialog, and anything the browser downloads is trapped in the container.

# Put a file where the profile's browser can use it: the body is the file, the header its name
curl --data-binary @report.csv -H "X-File-Name: report.csv" http://localhost:8080/api/profiles/<id>/files

# What this profile holds
curl http://localhost:8080/api/profiles/<id>/files

# Fetch one back (also serves what the browser downloaded)
curl -OJ http://localhost:8080/api/profiles/<id>/files/<artifact-id>

curl -X DELETE http://localhost:8080/api/profiles/<id>/files/<artifact-id>

The upload body is the file itself, not a form: it streams straight into the profile's store, so a file costs one copy on disk and an oversized one is refused from its Content-Length before a byte is read. X-File-Name is URL-encoded (%20 for a space), though a raw UTF-8 name works too; the stored type is the request's Content-Type when it is a real one, otherwise a guess from the name. An upload reports a container_path, which is what a CDP call that takes a path (DOM.setFileInputFiles, Input.dispatchDragEvent) hands to the page.

In the Docker build the live viewer gains a files button: upload from your own machine, drop a file straight onto the screen, or pull one back. Uploaded files also appear in the guest's own file dialog under Uploads — in the sidebar, so a website's "Choose file" button can reach them, and files the browser downloads are captured automatically and land in the same list.

On the native macOS and Windows builds the browser already shares your filesystem and writes to your own Downloads folder, so neither the sidebar shortcut nor download capture applies there. The endpoints above still work.

Download behaviour is browser-wide and last-writer-wins, so an automation client attached to the profile's CDP endpoint controls it: Playwright's connect_over_cdp, for example, sets its own download directory (or disables downloads entirely) as it initialises. While such a client is attached its downloads go where it asked, not into the profile's files — the Manager records nothing it cannot see, and never cancels a transfer it does not own. When such a client disconnects, Chromium falls back to its default download behaviour rather than to the Manager's, so capture is re-armed as soon as a proxied CDP connection closes.

Files live beside the profile, not inside it, so duplicating a profile's browser state never copies its documents. Deleting a profile deletes its files. Nothing expires on its own: the limits below are per profile. A file larger than ARTIFACT_MAX_BYTES is refused with 413, and an upload that would breach a profile's count or total is refused with 507; nothing is evicted to make room.

Variable	Default	Meaning
ARTIFACT_MAX_BYTES	268435456 (256 MiB)	Largest single file
ARTIFACT_MAX_COUNT	200	Files per profile
ARTIFACT_MAX_TOTAL_BYTES	2147483648 (2 GiB)	Total per profile

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 127.0.0.1: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/health endpoint remains unauthenticated (for Docker healthcheck); it exposes no system details. The /api/status endpoint (running counts, version) now requires authentication.

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).

Runtime UI configuration

The profile sidebar defaults to 16rem. To use a wider or narrower sidebar without changing the frontend build, set SIDEBAR_WIDTH to a CSS length:

docker run -p 127.0.0.1:8080:8080 -v cloakprofiles:/data -e SIDEBAR_WIDTH=20rem cloakhq/cloakbrowser-manager

Or in docker-compose.yml:

environment:
  - SIDEBAR_WIDTH=20rem

Supported units are px, rem, em, and vw. Invalid values fall back to 16rem.

License

• This application (GUI source code) — MIT. See LICENSE.
• CloakBrowser binary (compiled Chromium) — governed by version-specific subscription terms and may not be redistributed. See BINARY-LICENSE.md.

The GUI application requires the CloakBrowser Chromium binary to function. The binary is automatically downloaded once you add a license key 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

• lhq1363511234-arch — native Windows support foundation
• quorentindupres-dev — native macOS workflow and Manager integration concepts
• shellus: auth-gated status endpoint and unauthenticated health probe, offline VNC startup, multi-tag profile filters, and configurable sidebar width
• hayka-pacha — profile reset endpoint
• theaafofficial — duplicating a profile with its browser state, and per-profile files with download capture

Links

• CloakBrowser — github.com/CloakHQ/CloakBrowser
• Website — cloakbrowser.dev
• Bug reports — GitHub Issues
• Contact — [email protected]