Skip to content
Projects

polyackiy/camoufox-profile-manager

View on GitHub

polyackiy/camoufox-profile-manager has 93 GitHub stars and 28 forks. GitHot measured +1 stars in 24 hours. Last checked 2026-11-15 16:01 UTC. Last push 2026-11-06.

How these counts are measured

Measured star growth

in 24h
+1
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Self-hosted antidetect browser profile manager on Camoufox — profiles that stay the same machine across sessions

Self-hosted

README.md

Original

Camoufox Profile Manager

CI License: MIT Python 3.10+ Camoufox

A self-hosted, open-source manager for Camoufox antidetect browser profiles — a free alternative to AdsPower, Dolphin, Multilogin or GoLogin, for people who would rather run it themselves.

Each profile is one long-lived machine. It keeps the same fingerprint every session, along with its own cookies, storage and history, so an account opened from it in January still looks like the same computer in June.

Desktop release: download the latest stable release from Assets. macOS Apple Silicon and Intel, Windows x64, and Ubuntu/Debian x64 builds are produced by CI. Releases remain unsigned; certificates and macOS notarization are not planned and are not release requirements. OS security warnings can appear. See Getting started / Начало работы. See installation evidence and coverage limits. Chrome migration remains experimental.

For changes in 0.7.0 and the next priorities, see the changelog and roadmap.

The profiles list

What it does

  • A profile is the same machine every launch. Camoufox generates a fresh fingerprint on every start, which is right for a privacy tool and wrong for a long-lived account. The first launch resolves the fingerprint once and stores it; every launch after replays it. Location, timezone and WebRTC stay dynamic so they keep following the proxy. See docs/profile-settings.md.
  • Real device fingerprints. Create a profile from one of the 312 fingerprints Camoufox captured from actual machines, instead of a synthetic one.
  • Profiles and groups — create, edit, clone, delete, search, filter, bulk actions, and grouping by client or purpose. A clone gets its own machine by default: two profiles sharing one fingerprint are provably one computer.
  • Browser control — launch and stop a browser per profile; closing the window yourself is noticed and the session is cleaned up.
  • Scheduling — open a profile on a schedule (warming), and keep its pinned browser version current automatically. Hardware never rotates on a timer, on purpose — docs/scheduling.md.
  • Proxies, checked before you trust them. HTTP, HTTPS and SOCKS, with passwords encrypted at rest when CPM_SECRET_KEY is set. Check proxy reports where the proxy really comes out and whether the profile agrees with it — a timezone on a different clock from the exit country is the kind of contradiction a page can measure in two lines of JavaScript. The answer stays in the profiles list — exit address, country and latency under the proxy, green or amber or red — and a selection can be checked in one go.
  • Reusable proxy library — save named proxies, import a list and preview ordered assignments or assign one proxy to several closed profiles. Library passwords are write-only and require encryption. Assigned profiles retain independent copies. See the proxy guide and protocol acceptance matrix.
  • Multi-user, when you need it. Nothing to configure for the usual case: the app binds to loopback and is open. Set CPM_API_KEY for machine clients, or create an account (camoufox-pm user add) and humans get a login screen — argon2id hashes, HttpOnly session cookies, a logout that really invalidates. Administrators assign operator/viewer roles, profile access and separate export grants from Access, with a searchable activity log. See roles and access.
  • Encrypted device synchronization (experimental, opt-in). Opt in to closed-profile handoff through your self-hosted relay, approve trusted devices, and retain local recovery copies. Same tested OS/architecture/browser build only; local roles and schedules stay local. See synchronization setup and the support matrix.
  • Move a profile anywhere. Export a profile with its fingerprint and its browser data into one archive, and import it on another machine.
  • Cookie transfer — import and export standard JSON or Netscape cookie files, with validation, explicit merge/replacement and recovery before replacement. See cookies.
  • Templates and Firefox extensions — reuse browser settings in independent profiles and manage local add-ons without modifying Camoufox. Assigned add-ons travel with profile archives. Create numbered profile batches with an explicit proxy mapping and safe retry. See templates and extensions.
  • Tags and saved views — label profiles individually or in bulk, then save your search, filters and ordering for repeated work. See profile organization.
  • Bulk editing via Excel — docs/excel.md.
  • REST API and web UI, served on one port from one process.
  • English, Russian and Simplified Chinese UI. Switch languages in the sidebar or on the sign-in screen. Your choice is saved in this browser; the first visit follows its language preferences. Profile fingerprint languages stay separate.
  • Optional Chrome migration — import cookies and history from your own Chrome profiles (extras/chrome_migration).

What it looks like

The pinned machine on a profile

The pinned machine. This is the part that makes a profile an account rather than a browser window. Every value here was resolved once and is replayed on every launch — the screen, the CPU count, the GPU string, the font set, the user agent. Regenerate moves the profile to different hardware, deliberately, and tells you what that costs.

The profile above is pinned to one of the 312 devices Camoufox captured from real machines, so the combination is one that actually exists rather than an assembly of plausible parts.

Scheduled work System settings
Schedules Settings
Warming launches and browser-version refreshes. Hardware never rotates on a timer — why. Reports the effective configuration and warns when proxy passwords are unencrypted or the API is open.

Install and run

Desktop app — recommended

  1. Open Releases and choose the installer in Assets for your computer:

    Computer Download
    Mac, Apple Silicon (M1 or newer) camoufox-pm-macos-arm64.dmg
    Mac, Intel camoufox-pm-macos-x86_64.dmg
    Windows 10/11, Intel/AMD 64-bit camoufox-pm-windows-x86_64-setup.exe
    Ubuntu 22.04+/compatible Debian, Intel/AMD 64-bit camoufox-pm-linux-x86_64.deb
  2. Install and open Camoufox Profile Manager. You do not need Python, Node.js or a terminal. On Mac, drag the app into Applications first.

  3. Click Install browser in the app, wait for the download, and create your first profile. The app shows progress and provides a retry if installation fails.

Older releases may only offer Python packages. Desktop installers are unsigned under the release policy; macOS/Windows can show a security warning. Read the short beginner guide for installation, backups, Trash, updates, and where your data lives.

From source (developers)

Install uv and Node.js 20.9+; uv manages Python.

git clone https://github.com/polyackiy/camoufox-profile-manager.git
cd camoufox-profile-manager
uv sync --extra desktop
uv run python scripts/build_webui.py
uv run python -m camoufox_pm.desktop

To use a browser tab instead of a desktop window, run uv run camoufox-pm. This CLI keeps the existing data/profiles.db path by default. The desktop launcher uses a persistent OS data folder. See CLI options. On Linux, source desktop mode needs a supported pywebview GUI backend and system libraries; prefer the packaged .deb for the included Qt backend.

Build a standalone desktop bundle with uv sync --extra build followed by uv run python scripts/build_desktop.py --package. Packaging tools differ by platform; see releasing.

With Docker

docker compose up      # then open http://localhost:8000

One container serving the API and the UI on one port, like every other way of running it. The port is published on loopback only. Launching real browsers inside a container needs a virtual display; profile management, scheduling and the UI work as-is.

First steps

  1. Install the Camoufox browser when prompted, then click New profile.
  2. Give the profile a name. Leave advanced fingerprint fields at their defaults, or pick a real device if you need a particular machine.
  3. Add and check a proxy if you have one, or assign one from Proxies. HTTP/HTTPS and SOCKS5 support credentials; SOCKS4 credentials are unsupported.
  4. Press Run. The profile stays running until you click Stop or close its browser window.

Settings includes browser download retry, profile backups, and an update check. Deleted profiles go to Trash for recovery. Updates prepare a backup before offering an installer; replacing the app remains a manual installation step. Getting started explains these controls. The manager also provides complete offline data/browser recovery and explicit preview-release discovery. These additions are included in the v0.6.0-rc.4 installer release; signed automatic app replacement remains tracked in #63. Roles, profile grants and activity history are available under Access. Existing accounts migrate to administrators; export permission is separate from profile visibility.

For Simplified Chinese UI and Linux input-method setup, see 简体中文与 Linux 输入法.

Configuration

The desktop app creates its data folder and encryption key automatically. Advanced/source configuration uses environment variables (prefix CPM_); copy .env.example to .env if needed. Explicit configuration also overrides desktop defaults.

Variable Default Description
CPM_HOST 127.0.0.1 Bind address
CPM_PORT 8000 Port
CPM_DB_PATH data/profiles.db (CLI) SQLite database path; desktop uses the OS data folder
CPM_LEASE_TTL 120 Seconds a profile's lease survives without a heartbeat — how long a crashed instance keeps its profiles locked. Minimum 60
CPM_SECRET_KEY (empty) Fernet key; encrypts proxy passwords at rest
CPM_API_KEY (empty) If set, required as the X-API-Key header (machine clients)
CPM_SESSION_TTL_HOURS 168 Login session lifetime, in hours
CPM_SECURE_COOKIES 0 Force the session cookie's Secure flag (set behind a TLS proxy)
CPM_CORS_ORIGINS http://localhost:3000 Comma-separated allowed origins
CPM_WEBUI_DIR (auto) Override where the bundled web UI is served from

Generate an encryption key with:

uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Create the first administrator from the CLI, then manage users, roles and profile grants in Access in the web UI. CLI account management remains available: camoufox-pm user add <name> creates one, and from then on the API and UI require a login (see SECURITY.md).

Running more than one instance

Two instances against one database — the web UI and a CLI launch on the same machine, or two machines sharing a database file — must not open the same profile at once. One identity in two browsers means one cookie jar written from two places and the same account live from two IPs, which is exactly the correlation a profile exists to avoid.

Each launch therefore takes a lease on the profile, and a second instance is refused (409 over the API) until the browser closes. A lease is renewed while the browser runs and expires CPM_LEASE_TTL seconds after an instance stops renewing, so a machine that died does not lock its profiles forever.

camoufox-pm leases          # who holds what
camoufox-pm unlock <id>     # force-release, after checking the holder is gone

Force-release is CLI-only by design: it is the one operation that can put two browsers on one identity, so it takes shell access to the host rather than a button in the UI.

Editing is protected separately, because a profile is usually edited while nobody is running it. Each save carries the version it was based on, so two people editing the same profile no longer overwrite each other: the second save is refused, and the web UI says what changed and lets you apply your version deliberately rather than losing either edit.

Sharing the database file itself is safe between processes on one machine. Across machines it needs a filesystem whose locking SQLite can trust — which rules out most NFS and SMB mounts, where a lease may be read as free while another host holds it.

Documentation

Document What it covers
docs/getting-started.md Desktop installation and first steps
docs/automation.md Unreleased reusable workflows, scheduling and safe cancellation
docs/cli.md Every command and flag
docs/api.md The REST API, endpoint by endpoint
docs/profile-settings.md What each setting does, how the pinned machine works, and what Camoufox cannot do
docs/scheduling.md Scheduled launches and browser refresh, and why hardware rotation is not offered
docs/excel.md Bulk import and export
docs/accessibility-roadmap.md Plan for reaching non-technical users
docs/releasing.md Cutting a release
docs/signing.md Unsigned release policy and package integrity
docs/roadmap.md Merged work, release status and next priorities
docs/operation-diagnostics.md Safe diagnostic evidence for issue reports
CONTRIBUTING.md Working on the project
SECURITY.md Reporting a vulnerability

Measured, not assumed

Fingerprint behavior was checked against a running browser, and several results turned out differently than expected. The measurements are in the repository, as tests that fail if the behaviour changes:

What was measured Result
Does an unpinned profile keep its hardware between launches? No. The same profile reported 1600x900 then 3440x1440, 12 then 32 CPU cores, an NVIDIA then an AMD GPU. This is why pinning exists.
Is the canvas stable for a site across sessions? No, by default — it is stable within a session and per site, and changes on the next launch. stable_canvas fixes that, at the cost of being identical across sites. Both are asserted in browser tests.
Does Camoufox's canvas:seed property work? No. It is declared and passed through, and nothing reads it. Reported upstream as daijro/camoufox#721 with a reproduction.
What happens if a profile sets coordinates? Camoufox's IP lookup switches off, and Firefox then reports the host machine's own timezone — a real leak, found by reading the clock in a live browser. Fixed by filling that in ourselves.

The same discipline applies to the code: cleanup that could delete every profile directory, clones that shared a fingerprint with their source, and a release that reported the wrong version were all found by running the thing, not by reading it. See CHANGELOG.md.

Architecture

src/camoufox_pm/
├── main.py             FastAPI app; serves the API and the bundled UI
├── cli.py              the camoufox-pm command, including user accounts
├── config.py           environment-based settings
├── core/
│   ├── models.py            profiles, groups, browser settings, schedules
│   ├── database.py          SQLite storage and migrations
│   ├── profile_manager.py   profile lifecycle and browser control
│   ├── browser_session.py   running browsers
│   ├── fingerprint_store.py pinning, refreshing, and the real device presets
│   ├── fingerprint_generator.py  the high-level constraints a new profile starts from
│   ├── proxy_check.py       where a proxy exits, and whether the profile agrees
│   ├── scheduler.py         scheduled launches and browser refreshes
│   ├── profile_archive.py   whole-profile export and import
│   ├── excel_manager.py     bulk import and export
│   ├── auth.py              password hashing and login sessions
│   ├── crypto.py            proxy-password encryption at rest
│   └── cleanup.py           finding and removing orphaned profile directories
└── api/                routes, models, error shape, middleware
web/                    Next.js web interface
extras/chrome_migration/  optional Chrome → Camoufox migration

Backend: Python, FastAPI, SQLite, Camoufox + Playwright. Frontend: Next.js 16, React 19, TypeScript, Tailwind v4.

Development

uv sync --extra dev
uv run ruff check src tests
uv run mypy src/camoufox_pm
uv run pytest -m "not browser"    # fast suite
uv run pytest -m browser          # launches a real browser, needs `camoufox fetch`

See CONTRIBUTING.md.

Disclaimer

This tool is for lawful use only — for example testing, privacy, and managing multiple accounts in accordance with each site's terms of service. You are responsible for how you use it. Antidetect browsing does not make any activity that would otherwise be against a service's rules acceptable.

License

MIT © Camoufox Profile Manager Contributors.

Built on Camoufox by daijro.


Русская версия: README.ru.md.

Next stage: synchronization

Stage four architecture and plan proposes encrypted closed-profile handoff between trusted devices of one owner. This is planned work, not a shipped synchronization feature. Follow #82 for the implementation sequence and security acceptance gates.