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

> Configure CloakBrowser humanize presets default vs careful using the human_preset parameter. Optimize your browser behavior for speed or deliberate interaction.

- Repository: [CloakHQ/CloakBrowser](https://github.com/CloakHQ/CloakBrowser)
- Tags: how-to-guide
- Published: 2026-05-09

---

**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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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.

```python
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.

```python
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.

```python
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`.

```python
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.

```python
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.

```python
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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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.