How to Configure Humanize Presets: Default vs Careful Behavior in CloakBrowser

CloakBrowser provides two built-in humanize presets—default for standard human-like speed and careful for slower, more deliberate interactions—that you activate via the human_preset parameter in any launch function.

CloakBrowser’s humanize layer makes automated mouse, keyboard, and scroll actions indistinguishable from real user behavior by intercepting Playwright’s standard methods. The configuration system resides in the HumanConfig dataclass defined in cloakbrowser/human/config.py, which exposes two distinct presets stored in the module-level _PRESETS dictionary. When you configure humanize presets in CloakBrowser, you choose between normal-speed automation and a cautious mode designed for sensitive detection environments.

The Humanize Configuration Architecture

The humanize system centers on the HumanConfig dataclass in cloakbrowser/human/config.py. This file defines the timing parameters for mouse movements, typing delays, click holds, and scroll behaviors.

Two built-in presets populate the _PRESETS dictionary (lines 69–72):

• default: Uses the baseline values from instantiating HumanConfig() directly, representing normal human speed.
• careful: Generated by _careful_config() (lines 38–66), applying larger typing delays, longer click holds, slower scrolling, and enabling idle_between_actions for micro-movements.

When you call any launch function with humanize=True, the resolve_config() helper (lines 75–92) validates your human_preset selection against _PRESETS and returns a fully populated HumanConfig instance. This resolved configuration is then passed to the patching helpers in cloakbrowser/human/__init__.py, which replace Playwright’s Locator methods (click, type, fill, scroll_into_view_if_needed, etc.) with wrapped versions that respect the timing parameters.

Comparing Default and Careful Preset Behavior

default applies standard human-like variance to actions. Mouse movements follow natural bezier curves with moderate speed, typing occurs at average human words-per-minute rates, and clicks register with typical depression durations.

careful significantly extends all timing ranges. The preset increases pause durations between mouse bursts, extends the random delay before and after clicks, slows scroll velocity, and injects idle micro-movements between actions to mimic hesitation. Use this preset when operating on sites with aggressive bot detection that flag perfectly consistent timing patterns.

Implementing Presets in Launch Functions

All entry points in cloakbrowser/browser.py—including launch() (lines 64–66), launch_async() (lines 88–92), launch_context(), and launch_persistent_context()—accept three humanize-related arguments:

• humanize (bool): Enables the patching layer.
• human_preset (str): Selects "default" or "careful"; invalid values raise ValueError.
• human_config (dict): Optional overrides merged with the selected preset.

The following examples demonstrate each configuration pattern.

Using the Default Preset

When human_preset is omitted with humanize=True, the system automatically selects the "default" preset.

from cloakbrowser import launch

browser = launch(headless=False, humanize=True)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

Behind the scenes, resolve_config("default", None) returns a HumanConfig instance populated with baseline values.

Selecting the Careful Preset

Explicitly pass human_preset="careful" to activate slower, more cautious timing.

from cloakbrowser import launch

browser = launch(
    headless=False,
    humanize=True,
    human_preset="careful"
)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

This triggers resolve_config("careful", None), which retrieves the configuration built by _careful_config().

Overriding Specific Parameters

Fine-tune individual values while retaining the base preset using the human_config argument. Import HumanConfigOverrides to ensure type safety.

from cloakbrowser import launch
from cloakbrowser.human.config import HumanConfigOverrides

overrides: HumanConfigOverrides = {
    "mouse_burst_pause": (20, 35)  # Extend pause between mouse bursts

}

browser = launch(
    headless=False,
    humanize=True,
    human_preset="careful",
    human_config=overrides
)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

The resolve_config function merges your overrides with the careful preset values (lines 98–101), applying only your specified deviation while keeping all other careful timings intact.

Async API Implementation

The async launch functions follow an identical resolution path via resolve_config and patch_browser_async.

import asyncio
from cloakbrowser import launch_async

async def main():
    browser = await launch_async(
        headless=False,
        humanize=True,
        human_preset="careful"
    )
    page = await browser.new_page()
    await page.goto("https://example.com")
    await browser.close()

asyncio.run(main())

Persistent Context with Presets

Persistent contexts support the same humanize configuration, storing your profile locally while applying the selected preset to all interactions.

from cloakbrowser import launch_persistent_context

ctx = launch_persistent_context(
    "./profile",
    headless=False,
    humanize=True,
    human_preset="careful"
)
page = ctx.new_page()
page.goto("https://example.com")
ctx.close()

Debugging the Resolved Configuration

Inspect concrete timing values by calling resolve_config directly before launching.

from cloakbrowser.human.config import resolve_config

cfg = resolve_config("careful")
print(cfg)

This prints the fully merged HumanConfig instance, revealing the exact millisecond ranges and boolean flags active for your session.

Summary

• Select behavior via human_preset, choosing "default" for normal speed or "careful" for deliberate, detection-resistant actions.
• Enable the humanize layer with humanize=True in any launch function.
• Fine-tune specific parameters by passing a human_config dictionary that overrides preset values.
• Apply these configurations consistently across sync, async, and persistent context launches without modifying core library code.

Frequently Asked Questions

What is the difference between default and careful presets in CloakBrowser?

The default preset applies baseline human-like timing suitable for most automation tasks, while the careful preset systematically increases delays between actions, extends click durations, slows scrolling, and adds idle micro-movements to evade detection on heavily monitored sites.

How do I override specific timing values while keeping a preset?

Pass a dictionary to the human_config argument in your launch function. According to cloakbrowser/human/config.py, the resolve_config function merges your overrides with the selected preset, allowing you to modify specific fields like mouse_burst_pause without redefining the entire configuration.

Can I use humanize presets with persistent browser contexts?

Yes. Both launch_persistent_context() and launch_persistent_context_async() accept humanize, human_preset, and human_config arguments (see lines 52–55 and 77–80 of cloakbrowser/browser.py), applying the humanize layer to all pages within the persistent context.

What happens if I provide an invalid preset name?

The resolve_config function validates the human_preset argument against the _PRESETS dictionary keys. Supplying any value other than "default" or "careful" raises a ValueError immediately upon launch, preventing misconfiguration before the browser initializes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}