CamouMgr

CamouMgr is a desktop manager for Camoufox profiles. It gives you a local UI for creating browser profiles, assigning proxies, choosing an OS fingerprint, launching sessions, and moving profiles in and out of ZIP archives.

The app also starts a small local REST API next to the GUI, so the same profile operations can be scripted.

What is in the app

Create, edit, rename, and delete profiles.
Assign a proxy per profile.
Choose an OS type per profile: windows, linux, or macos.
Launch and stop browser sessions from the GUI.
Select multiple profiles and run bulk launch, stop, or delete actions.
Check proxy connectivity from the profile dialog.
Export profiles to ZIP archives, with or without browser data.
Import profiles from ZIP archives, with optional overwrite behavior.
View recent activity in the sidebar log and open a larger log window.
Page through the profile list when you have more than 10 profiles.
Use the built-in local API for automation.

Requirements

Python 3.10 or newer
A working Python environment that can install the packages in requirements.txt

The repository includes run_cmngr.bat for Windows. The Python entry point works directly as well.

Installation

git clone https://github.com/DedInc/camoumgr.git
cd camoumgr

python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux/macOS
source .venv/bin/activate

pip install -r requirements.txt

Running the app

Start the GUI and local API together:

python -m src.main

On Windows you can also use:

run_cmngr.bat

When the app starts, it launches:

the Flet desktop UI
the FastAPI server on http://127.0.0.1:8000 by default

Swagger UI is available at http://127.0.0.1:8000/docs and ReDoc at http://127.0.0.1:8000/redoc.

Configuration

All configuration is optional. If you want to override defaults, copy .env.example to .env in the project root.

| Variable | Default | Description | | --- | --- | --- | | CAMOUMGR_PROFILES_FILE | profiles.json | JSON file used to store profile metadata. | | CAMOUMGR_DATA_DIR | camoufox_data | Directory that stores per-profile browser data. | | CAMOUMGR_LOG_DIR | logs | Directory for daily log files. | | CAMOUMGR_LOG_LEVEL | INFO | Python log level. | | CAMOUMGR_PROXY_TIMEOUT | 10 | Default timeout, in seconds, for proxy checks. | | CAMOUMGR_API_HOST | 127.0.0.1 | Host used by the local API server. | | CAMOUMGR_API_PORT | 8000 | Port used by the local API server. |

Storage layout

By default, the project writes data to these locations:

profiles.json - profile metadata
camoufox_data\<profile-name>\ - browser data for each profile
logs\camoumgr_YYYYMMDD.log - daily log file

Exported ZIP files contain:

profile.json
data\... when export is run with browser data included

Proxy format

Accepted proxy formats:

host:port
http://host:port
https://host:port
socks4://host:port
socks5://host:port
http://user:pass@host:port
socks5://user:pass@host:port

Rules enforced by the validator:

scheme is optional
supported schemes are http, https, socks4, and socks5
port must be in the range 1-65535
an empty proxy value is allowed

The GUI proxy checker uses the configured timeout and reports either the detected IP or the failure message.

Profile name rules

Profile names are validated before they are saved.

must not be empty
must be 64 characters or fewer
must not start or end with spaces
must not contain < > : " / \ | ? *
must not be a reserved Windows name such as CON, PRN, AUX, NUL, COM1-COM9, or LPT1-LPT9

Local API reference

The API is intended for local automation. There is no authentication layer in the code, so leaving it bound to localhost is the safe default.

Base prefix:

/api/v1

Health

| Method | Path | Notes | | --- | --- | --- | | GET | /health | Returns a basic success message. |

Example response:

{
  "success": true,
  "message": "CamouMgr API is running"
}

Profiles

| Method | Path | Notes | | --- | --- | --- | | GET | /profiles | List all profiles. | | POST | /profiles | Create a profile. | | GET | /profiles/{name} | Get one profile, including data_dir and is_running. | | PATCH | /profiles/{name} | Update only the supplied fields. | | DELETE | /profiles/{name} | Delete a profile and its data directory. | | GET | /profiles/{name}/data-dir | Return the resolved data directory and whether it exists. | | POST | /profiles/{name}/export | Export one profile to a ZIP file. | | POST | /profiles/import | Import one profile from a ZIP file. |

Create profile request:

{
  "name": "my-profile",
  "proxy": "socks5://user:pass@127.0.0.1:1080",
  "os_type": "linux"
}

Create and update fields:

name: string
proxy: string or null
os_type: string, default windows

Update uses the same fields, but all of them are optional.

Profile response shape:

{
  "name": "my-profile",
  "proxy": "socks5://user:pass@127.0.0.1:1080",
  "os_type": "linux",
  "data_dir": "C:\\path\\to\\camoufox_data\\my-profile",
  "is_running": false
}

Export request:

{
  "export_dir": "C:\\Exports",
  "include_data": true
}

Export response:

{
  "success": true,
  "zip_path": "C:\\Exports\\my-profile_20260313_134500.zip",
  "error": null
}

Import request:

{
  "zip_path": "C:\\Exports\\my-profile_20260313_134500.zip",
  "overwrite": false
}

Import response:

{
  "success": true,
  "profile_name": "my-profile",
  "error": null
}

Profile endpoint behavior worth knowing:

POST /profiles returns 201 Created
PATCH /profiles/{name} can return 409 when a rename conflicts, or when the browser for that profile is running and the name change is blocked
DELETE /profiles/{name} returns 409 if the browser is still running
POST /profiles/{name}/export requires export_dir to already exist
POST /profiles/import requires profile.json inside the ZIP archive

Browser

| Method | Path | Notes | | --- | --- | --- | | GET | /browser | List names of running browser sessions. | | GET | /browser/{name}/status | Return running status for one profile. | | POST | /browser/{name}/launch | Start a browser session asynchronously. | | POST | /browser/{name}/stop | Stop a running browser session. |

Running browser response:

{
  "running": ["profile-a", "profile-b"],
  "count": 2
}

Launch response:

{
  "success": true,
  "message": "Browser launching for 'my-profile'"
}

Browser endpoint behavior worth knowing:

POST /browser/{name}/launch returns 202 Accepted
launch is asynchronous; use GET /browser/{name}/status or GET /browser to check state
POST /browser/{name}/launch returns 409 if the profile is already running
POST /browser/{name}/stop returns 409 if the profile is not running

Proxy

| Method | Path | Notes | | --- | --- | --- | | POST | /proxy/check | Validate and test a proxy. |

Request:

{
  "proxy": "socks5://user:pass@127.0.0.1:1080",
  "timeout": 10
}

Response:

{
  "success": true,
  "message": "203.0.113.10"
}

Quick API examples

Create a profile:

curl -X POST http://127.0.0.1:8000/api/v1/profiles ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"work\",\"proxy\":\"socks5://user:pass@127.0.0.1:1080\",\"os_type\":\"linux\"}"

Get the resolved data directory:

curl http://127.0.0.1:8000/api/v1/profiles/work/data-dir

Launch a browser:

curl -X POST http://127.0.0.1:8000/api/v1/browser/work/launch

Check whether it is running:

curl http://127.0.0.1:8000/api/v1/browser/work/status

Check a proxy:

curl -X POST http://127.0.0.1:8000/api/v1/proxy/check ^
  -H "Content-Type: application/json" ^
  -d "{\"proxy\":\"socks5://user:pass@127.0.0.1:1080\",\"timeout\":10}"

Project layout

src\
  api\         FastAPI app, routes, and schemas
  core\        config, container, logging, events
  interfaces\  service protocols
  models\      profile model
  services\    profile, browser, and proxy services
  ui\          Flet UI, dialogs, and actions
  utils\       validation and helper utilities

License

MIT License

Camoumgr

Install / Use

README