Camoufy docs

Camoufy 1.1.1

Getting started

• Unzip the download anywhere and run camoufy.exe. The interface opens in its own window, and the program also sits in the tray.
• Open the Engine page and install a Camoufox release from GitHub. It is unpacked into engine\camoufox\ inside the program folder.
• On the Proxies page, paste your proxy list and press Check. You get each proxy's exit IP, country and latency.
• Create a profile, pick a proxy and press Start. The profile opens on its check page, which compares what the browser reports with the fingerprint.

Linux and Docker

On Linux, Camoufy runs as a Docker image for amd64 and arm64. It is the same program without a window of its own: you open the interface in your browser.

docker run -d --name camoufy --restart unless-stopped -p 127.0.0.1:18800:18800 -v camoufy-data:/data --shm-size=2g --stop-timeout 30 camoufy/camoufy

Or save docker-compose.yml into an empty folder and run docker compose up -d there. Both do the same thing.

• Sign in. docker logs camoufy prints a link with the API key. Open it once and the browser remembers the key.
• Engine. Install it from the Engine page, as on Windows. It is stored in the data volume.
• Profile screens. Every profile with a window gets its own virtual screen, sized like the screen in its fingerprint. The Screen button next to a running profile opens it in a tab, with mouse, keyboard and paste.
• Headless. In Docker a headless start runs on a virtual screen as well, and the Screen button works for it. The browser's own headless mode opens a window larger than the screen of the fingerprint, which a site can notice.
• Data. Profiles, settings, the engine and logs live in the camoufy-data volume and survive updates.
• Updates. With compose: docker compose pull, then docker compose up -d. With plain docker run: docker pull camoufy/camoufy, then docker rm -f camoufy, then the run command again. Removing the container keeps your data, it lives in the volume. Stop your profiles first.
• Stopping. docker stop camoufy closes the running profiles, saves their sessions and stops the program. The Quit button in Settings only restarts it, because Docker starts the container again.
• Access. The port is published to this computer only. To reach it from another machine, use an SSH tunnel or put a reverse proxy with HTTPS in front, see Your own domain. The server itself speaks plain HTTP.
• Port. The Windows version uses 18800 too. To run both on one computer, change the first number in 127.0.0.1:18800:18800.

The options in the command matter. --shm-size=2g keeps browser tabs from crashing, and --stop-timeout 30 gives running profiles time to close and save their sessions.

Your own domain

To open Camoufy at an address like https://camoufy.example.com, keep the container on 127.0.0.1:18800 and put nginx in front of it. Replace the domain and the certificate paths with yours.

server {
    listen 443 ssl;
    server_name camoufy.example.com;

    ssl_certificate     /etc/ssl/camoufy.example.com.crt;
    ssl_certificate_key /etc/ssl/camoufy.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:18800;
        proxy_http_version 1.1;

        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # profile screens use WebSocket
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;

        # live status updates are a long, unbuffered response
        proxy_buffering off;
        proxy_read_timeout 3600;
        proxy_send_timeout 3600;

        # profile and add-on uploads
        client_max_body_size 512m;
    }
}

server {
    listen 80;
    server_name camoufy.example.com;
    return 301 https://$host$request_uri;
}

• Host header. Camoufy compares it with the page address before it opens a screen, so nginx has to pass it on unchanged.
• HTTPS. The sign-in cookie is marked secure when the request arrives with X-Forwarded-Proto: https. Without HTTPS the API key would cross the network in plain text.
• Signing in. Open https://camoufy.example.com/?api_key=KEY once. The key is in docker logs camoufy. Anyone without the key gets the sign-in form and nothing else.

Profile password

A profile can have its own password, set on the General tab of the profile editor. While such a profile is stopped, its cookies, saved logins, history and site storage sit on disk as one encrypted file. Name, tags, proxy and fingerprint stay readable, so the profile still shows in the list.

• Start. Camoufy asks for the password. In the API it is the password field of the start request, and in MCP the password argument of start_profile.
• Stop. The data is encrypted again and the plain copy is removed, also after a browser crash. While the profile runs, its state is saved in encrypted form every minute.
• Disk or memory. On Linux the profile can be decrypted into memory, so its plain data never touches the disk. In Docker that memory comes out of --shm-size.
• Screens in Docker. The browser session that started the profile sees its screen. Any other session signed in with the API key has to enter the profile password first.
• No recovery. A lost password cannot be reset. The data stays encrypted.

While a profile runs, its data is decrypted, because the browser cannot work on an encrypted folder.

Proxies

One proxy per line, in any of these forms. A line without a scheme is HTTP.

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

Timezone, locale, coordinates and the WebRTC address of a profile follow the proxy's exit IP. They are resolved through the proxy on every start and cached in the profile's geo.json.

Sticky sessions

Residential providers keep an exit IP for as long as the login carries the same session id. Put {session} where the provider expects it. Camoufy fills in a different id for every profile, so each one keeps its own IP.

gate.provider.net:7000:user-country-de-session-{session}:password

"Change IP" on the Proxy tab of a profile issues a new session at once, without restarting the browser. "New identity" in the profile menu does the same with only "New IP" ticked. After three failed connections in a row Camoufy rotates the session by itself.

Tor

Install Tor on the Engine page, then choose Tor as the profile's proxy mode and, optionally, an exit country. Each Tor profile runs its own tor process with its own circuits. If your network blocks Tor, paste bridge lines in Settings.

Cookies and export

Cookies in Netscape format (cookies.txt) are imported from the profile menu before the profile starts. A profile can be exported to a .cbprofile file with its fingerprint, cookies and, if you choose, its proxy and add-ons, and imported into another copy of Camoufy.

HTTP API

On Windows the API listens on 127.0.0.1:18800. In Docker it answers at the same address as the interface, for example https://camoufy.example.com. Send the key from Settings in the X-Api-Key header, or as Authorization: Bearer.

curl -H "X-Api-Key: $KEY" -X POST http://127.0.0.1:18800/api/v1/profiles/p_3a91c/start \
     -d '{"headless": true, "automation": "bidi"}'

Every request with its fields and answers is in the HTTP API reference.

To drive a browser from another machine, start the profile with automation "bidi" and connect a WebDriver BiDi client (Selenium, Puppeteer) to the remote_ws path from the answer:

wss://camoufy.example.com/api/v1/profiles/p_3a91c/bidi?api_key=KEY

The page cannot tell it is automated this way: navigator.webdriver stays false and input arrives as real device events. For a profile with a password, remote_ws carries a token that only the start request returns, so nobody else with the API key can attach to it.

The ws_endpoint field and the launch recipe point at 127.0.0.1 and at local paths. They are for scripts that run on the same machine as Camoufy, which with Docker means inside the container.

Python client

The API page inside the program links to camoufy.py and a Playwright example. Next to the program the client finds the key by itself. For another address pass both: Camoufy(api_key="KEY", base="https://camoufy.example.com"). A profile with a password takes password="..." in start and playwright_context.

from camoufy import Camoufy

cb = Camoufy()
p = cb.create("Shop DE", proxy_id="px_0b90a0")
with cb.playwright_context(p["id"], headless=True) as ctx:
    ctx.new_page().goto("https://example.com")

AI control (MCP)

Camoufy is an MCP server, so an AI model can run your profiles: start one, open a site, read the page, click, type, scroll and take screenshots. It works with Claude Desktop, Claude Code, Cursor and LM Studio. The API page inside the program shows these configs with your real path and key filled in.

Claude Desktop, Cursor and LM Studio (claude_desktop_config.json or mcp.json):

{
  "mcpServers": {
    "camoufy": { "command": "D:\\Camoufy\\camoufy.exe", "args": ["mcp"] }
  }
}

Claude Code:

claude mcp add camoufy -- "D:\Camoufy\camoufy.exe" mcp

In Docker the command is docker exec -i camoufy camoufy mcp, and the API page shows it ready to copy.

No key is needed here. On Windows, if Camoufy is closed it starts in the tray.

The config above runs Camoufy on the same computer as the AI client. When Camoufy runs on a server, the client connects to its address with the API key. Cursor and LM Studio (mcp.json):

{
  "mcpServers": {
    "camoufy": {
      "url": "https://camoufy.example.com/mcp",
      "headers": { "X-Api-Key": "KEY" }
    }
  }
}

Claude Code:

claude mcp add --transport http camoufy https://camoufy.example.com/mcp --header "X-Api-Key: KEY"

Claude Desktop starts a command and has no place for a header, so it reaches the server over SSH:

{
  "mcpServers": {
    "camoufy": {
      "command": "ssh",
      "args": ["[email protected]", "docker", "exec", "-i", "camoufy", "camoufy", "mcp"]
    }
  }
}

On the same computer the URL form works too, at http://127.0.0.1:18800/mcp. The interface keeps working while a model is connected, and the Screen button shows what the model is doing.

The model reads a page as text with numbered elements and acts on those numbers. Clicks and typing are real input events with mouse movement and pauses between keys, and the page cannot see the helper script. A profile you started from the window without automation gets restarted when the model takes it over. Your AI client asks before each action unless you allow it, and every action is written to data/logs/mcp.log (typed text only as its length, passwords not at all). A profile with a password starts only when the model is given that password.