Camoufox Documentation

Camoufox uses a thread-safe C++ key-value store called RoverfoxStorageManager to manage fingerprinting values. Values are keyed by a unique userContextId derived from Firefox's container identity system.

Storage Mechanism:

• When window.setXxx() is called, the value is stored in a local nsTHashMap cache.
• The value is also written to Firefox Preferences with a roverfox.s. prefix (all types are serialized as CString internally).
• In content processes, values are synchronized to the parent process via synchronous IPC (SendRoverfoxStoragePut).

Fallback Behavior: Certain patches provide a global fallback (using ucid=0) so that workers unable to resolve a specific userContextId can still access the values. Patches with this fallback include: audio, canvas, navigator (all 4 functions), timezone, and webgl. Patches without this fallback include: font-spacing, screen, font-list, speech-voices, and webrtc-ip.

To support Firefox's Fission (site isolation), Camoufox uses the cross-process-storage.patch to ensure fingerprinting values are available in worker processes even when the local in-process HashMap is empty.

Key Components:

1. IPDL Sync Messages: Uses sync RoverfoxStoragePut to write to the parent process and sync RoverfoxStorageGet to read from it. These are synchronous to ensure availability before workers start.
2. Parent Process Handlers: ContentParent.cpp handles these messages, allowing only preference names starting with "roverfox.s." for security.
3. Preference Whitelist: The prefix "roverfox.s." is whitelisted in Preferences.cpp to prevent Firefox from stripping these dynamically-created strings during cross-process sync.

Thread Safety Note: Synchronous IPC calls are only permitted on the main thread. If a non-main thread (like HarfBuzz font rendering or the compositor) attempts to read a value, the system falls back to the local cache and Firefox Preferences only.

Camoufox is a headless, undetectable Firefox fork optimized for web scraping and AI agents. It is designed to blend into normal traffic by providing a fresh identity for every run, drawn from real-world device distributions.

Key Capabilities:

• Undetectable Automation: Page automation is hidden from JavaScript inspection.
• Fingerprint Injection & Rotation: Spoofs navigator properties (device, OS, hardware), screen/viewport properties, geolocation, timezone, locale, WebRTC IP (at protocol level), and audio/voice properties without using JS injection.
• Anti-Graphical Fingerprinting: Spoofs WebGL parameters, extensions, context attributes, shader precision, and fonts.
• Automation Optimizations: Includes human-like mouse movement, ad blocking/circumvention, and removal of CSS animations for speed.
• Efficiency: Debloated for memory efficiency and fast launches.
• Compatibility: Drop-in Playwright compatibility via the Python interface.

Camoufox provides per-context isolation via specific JavaScript functions that allow each Playwright context to have a unique, deterministic fingerprint. This prevents cross-context correlation when running multiple concurrent sessions.

To apply these fingerprints, use context.addInitScript(). This ensures the functions are called on every new page, tab, or navigation before any website scripts execute.

Important Notes:

• Self-Destruction: All fingerprinting functions self-destruct after the first call. They cannot be detected by website code via typeof window.setXxx after execution.
• Guards: Always use typeof checks (e.g., if (typeof window.setTimezone === 'function')) within your init script to prevent ReferenceError if the patches are not present or if the function has already self-destructed.

const { firefox } = require('playwright');

const browser = await firefox.launch({
  executablePath: '/path/to/camoufox',
});

const context = await browser.newContext({
  viewport: { width: 1280, height: 720 },
});

// Apply fingerprints via addInitScript — fires on every new page automatically
await context.addInitScript((values) => {
  const w = window;

  if (typeof w.setFontSpacingSeed === 'function') {
    w.setFontSpacingSeed(values.fontSpacingSeed);
  }
  if (typeof w.setAudioFingerprintSeed === 'function') {
    w.setAudioFingerprintSeed(values.audioFingerprintSeed);
  }
  if (typeof w.setTimezone === 'function') {
    w.setTimezone(values.timezone);
  }
  if (typeof w.setScreenDimensions === 'function') {
    w.setScreenDimensions(values.screenWidth, values.screenHeight);
  }
  if (typeof w.setScreenColorDepth === 'function') {
    w.setScreenColorDepth(values.screenColorDepth);
  }
  if (typeof w.setWebRTCIPv4 === 'function') {
    w.setWebRTCIPv4(values.webrtcIPv4);
  }
  if (typeof w.setNavigatorPlatform === 'function') {
    w.setNavigatorPlatform(values.navigatorPlatform);
  }
  if (typeof w.setNavigatorOscpu === 'function') {
    w.setNavigatorOscpu(values.navigatorOscpu);
  }
  if (typeof w.setNavigatorHardwareConcurrency === 'function') {
    w.setNavigatorHardwareConcurrency(values.hardwareConcurrency);
  }
  if (typeof w.setNavigatorUserAgent === 'function') {
    w.setNavigatorUserAgent(values.userAgent);
  }
  if (typeof w.setWebGLVendor === 'function') {
    w.setWebGLVendor(values.webglVendor);
  }
  if (typeof w.setWebGLRenderer === 'function') {
    w.setWebGLRenderer(values.webglRenderer);
  }
  if (typeof w.setCanvasSeed === 'function') {
    w.setCanvasSeed(values.canvasSeed);
  }
  if (values.fontList && values.fontList.length > 0 && typeof w.setFontList === 'function') {
    w.setFontList(values.fontList.join(','));
  }
  if (values.speechVoices && typeof w.setSpeechVoices === 'function') {
    w.setSpeechVoices(values.speechVoices);
  }
}, {
  fontSpacingSeed: 12345678,
  audioFingerprintSeed: 87654321,
  timezone: 'America/New_York',
  screenWidth: 1920,
  screenHeight: 1080,
  screenColorDepth: 24,
  webrtcIPv4: '203.0.113.1',  // your proxy IP
  navigatorPlatform: 'MacIntel',
  navigatorOscpu: 'Intel Mac OS X 10.15',
  hardwareConcurrency: 8,
  userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:146.0) Gecko/20100101 Firefox/146.0',
  webglVendor: 'Intel Inc.',
  webglRenderer: 'Intel Iris OpenGL Engine',
  canvasSeed: 55555555,
  fontList: ['Arial', 'Helvetica', 'Georgia', 'Courier New', 'Verdana', 'Times New Roman'],
  speechVoices: 'Microsoft David,Microsoft Zira,Google US English',
});

const page = await context.newPage();
await page.goto('https://example.com');