> ## Documentation Index
> Fetch the complete documentation index at: https://intunedhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Stealth mode, CAPTCHA solving, and proxies

## Overview

Websites block automated traffic by examining browser fingerprints, detecting automation frameworks, and checking IP reputation. Intuned provides four features to help your automations avoid detection: proxies, headful mode, stealth mode, and CAPTCHA solving.

<Tip>
  **Before you start:** - Stealth mode and CAPTCHA solving are experimental—let
  us know if you encounter issues - Check the site's terms of service and
  `robots.txt` to ensure responsible automation - Stealth mode and CAPTCHA
  solving only work on the Intuned platform, not with local `intuned run`
  commands
</Tip>

## Which features do you need?

Start simple and add features as needed. Each addresses a different blocking mechanism:

| If you're seeing...              | Enable...                    |
| -------------------------------- | ---------------------------- |
| IP-based blocking, rate limiting | Proxies                      |
| Headless browser detection       | Stealth mode or headful mode |
| Fingerprint/automation detection | Stealth mode                 |
| CAPTCHAs blocking your flow      | CAPTCHA solving              |

## Proxies

Proxies route traffic through different IP addresses, making your requests appear to come from different locations. Use them to bypass IP-based blocking and rate limiting.

### Proxy types

| Type            | Description                          | Cost               | Best for                                          |
| --------------- | ------------------------------------ | ------------------ | ------------------------------------------------- |
| **Residential** | IPs from real ISP users              | Per GB (expensive) | Heavily protected sites that block datacenter IPs |
| **Datacenter**  | IPs from cloud data centers          | Per IP/month       | General scraping where IP rotation is sufficient  |
| **ISP**         | Datacenter-hosted but ISP-registered | Per IP/month       | Balance of reliability and cost                   |

<Warning>
  Residential proxies bill per GB of traffic. Monitor usage carefully to avoid
  unexpected charges.
</Warning>

### Configure proxies

Configure proxies at three levels:

**Run level**—Use the `proxy` parameter when creating a Run:

<CodeGroup dropdown>
  ```typescript theme={null}
  import { IntunedClient } from "@intuned/client";

  const intunedClient = new IntunedClient({
    workspaceId: "123e4567-e89b-12d3-a456-426614174000",
    apiKey: process.env["INTUNED_API_KEY"] ?? "",
  });

  async function run() {
    const result = await intunedClient.projects.runs.start("my-project", {
      parameters: {
        param1: "value1",
        param2: 42,
        param3: true,
      },
      api: "my-awesome-api",
      proxy: "http://username:password@domain:port",
    });

    console.log(result);
  }

  run();
  ```

  ```python theme={null}
  from intuned_client import IntunedClient
  from intuned_client import models
  import os


  with IntunedClient(
      workspace_id="123e4567-e89b-12d3-a456-426614174000",
      api_key=os.getenv("INTUNED_API_KEY", ""),
  ) as ic_client:

      res = ic_client.projects.runs.start(
        project_name="my-project",
        body=models.RunStartRequestBody(
          parameters={
              "param1": "value1",
              "param2": 42,
              "param3": True,
          },
          api="my-awesome-api",
          proxy="http://username:password@domain:port",
        ),
      )

      # Handle response
      print(res)
  ```
</CodeGroup>

**AuthSession level**—Use for authenticated sessions that need consistent IPs:

<CodeGroup dropdown>
  ```typescript theme={null}
  import { IntunedClient } from "@intuned/client";

  const intunedClient = new IntunedClient({
    workspaceId: "123e4567-e89b-12d3-a456-426614174000",
    apiKey: process.env["INTUNED_API_KEY"] ?? "",
  });

  async function run() {
    const result = await intunedClient.projects.authSessions.create.start(
      "my-project",
      {
        parameters: {
          username: "john.doe",
          password: "password",
        },
        proxy: "http://proxy.example.com:8080",
      }
    );

    console.log(result);
  }

  run();
  ```

  ```python theme={null}
  from intuned_client import IntunedClient
  from intuned_client import models
  import os


  with IntunedClient(
      workspace_id="123e4567-e89b-12d3-a456-426614174000",
      api_key=os.getenv("INTUNED_API_KEY", ""),
  ) as ic_client:

      res = ic_client.projects.auth_sessions.create.start(
        project_name="my-project",
        body=models.AuthSessionsCreateStartRequestBody(
          parameters={
              "username": "john.doe",
              "password": "password",
          },
          id="auth-session-123",
          proxy="http://proxy.example.com:8080",
        ),
      )

      # Handle response
      print(res)
  ```
</CodeGroup>

**Job level**—Use the `proxy` field in job settings. See [Job Settings](/client-apis/api-reference/projectsjobs/create-job).

<Tip>
  Configure proxies at the AuthSession level when you need consistent IP
  addresses to maintain login state.
</Tip>

### Best practices

* **Test without proxies first**—Use datacenter proxies or your own IP before purchasing residential proxies
* **Use residential selectively**—Only for sites that actively block datacenter IPs. Monitor traffic usage due to per-GB billing
* **Rotate proxies**—Distribute requests across multiple proxies to avoid rate limiting
* **Test before committing**—Some proxies are slow or unreliable. Verify performance with your target sites before production use
* **Combine with other features**—Proxies work best alongside stealth mode and headful mode

## Headful mode

Headful mode runs the browser with a visible GUI instead of headless. This produces a more realistic browser fingerprint and avoids headless-specific detection.

### Enable headful mode

Add the `headful` key to your `intuned.json`:

```json theme={null}
{
  "headful": true
}
```

## Stealth mode

Stealth mode runs your automation on Intuned Browser, our Chromium-based stealth browser, and applies additional anti-detection flags at launch. This reduces common automation fingerprints and makes your browser less likely to be flagged as a bot.

### Requirements

* **Playwright v1.55 or higher**—Check [Playwright browsers support](/main/05-references/playwright-browsers-support) for supported versions. We recommend upgrading to the latest Playwright version for the best stealth mode compatibility.
* **Platform only**—Doesn't work with local CLI execution

### Enable stealth mode

```json theme={null}
{
  "stealthMode": {
    "enabled": true
  }
}
```

<Tip>
  If you change stealth settings while a browser session is already open in the
  IDE, restart that browser session so the new browser binary and launch flags
  are applied.
</Tip>

## CAPTCHA solving

When you enable CAPTCHA solving, Intuned automatically detects and solves CAPTCHAs during your automation.

<Note>
  CAPTCHA is a general term for challenges that verify you're human. This
  includes reCAPTCHA, hCaptcha, Cloudflare Turnstile, and similar services.
</Note>

<Info>
  CAPTCHA solving can take time. The duration depends on the CAPTCHA type and
  the difficulty settings configured on the target website. Simple checkbox
  challenges may resolve in seconds, while more complex challenges can take
  longer.
</Info>

### Requirements

* **Headful mode required**—Set `headful` to `true`
* **Stealth mode required**—Set `stealthMode.enabled` to `true`
* **Hosted projects or deployed runs**—Doesn't work in local CLI

### Supported CAPTCHA types

* Google reCAPTCHA v2 and Enterprise
* Cloudflare Turnstile and Cloudflare interstitial challenges
* AWS WAF CAPTCHA
* GeeTest
* FunCaptcha (Arkose Labs)
* Lemin CAPTCHA
* Custom image CAPTCHAs (with selectors)
* Text CAPTCHAs (with selectors)

### Configure CAPTCHA solving

<Tabs>
  <Tab title="Enable Cloudflare">
    ```json theme={null}
    {
      "headful": true,
      "stealthMode": {
        "enabled": true
      },
      "captchaSolver": {
        "enabled": true,
        "cloudflare": {
          "enabled": true
        },
        "settings": {
          "autoSolve": true,
          "solveDelay": 2000,
          "maxRetries": 6,
          "timeout": 30000
        }
      }
    }
    ```
  </Tab>

  <Tab title="Specific providers">
    ```json theme={null}
    {
      "headful": true,
      "stealthMode": {
        "enabled": true
      },
      "captchaSolver": {
        "enabled": true,
        "googleRecaptcha": {
          "enabled": true
        },
        "settings": {
          "autoSolve": true,
          "solveDelay": 2000,
          "maxRetries": 3,
          "timeout": 30000
        }
      }
    }
    ```
  </Tab>

  <Tab title="Custom image CAPTCHAs">
    For custom image-based CAPTCHAs, you must provide CSS selectors to identify the CAPTCHA elements:

    ```json theme={null}
    {
      "headful": true,
      "stealthMode": {
        "enabled": true
      },
      "captchaSolver": {
        "enabled": true,
        "customCaptcha": {
          "enabled": true,
          "imageLocators": ["#captcha-image", ".custom-captcha img"],
          "inputLocators": ["#captcha-input", ".captcha-field input"],
          "submitLocators": ["#submit-button", "button[type='submit']"]
        },
        "settings": {
          "autoSolve": true,
          "solveDelay": 2000,
          "maxRetries": 3,
          "timeout": 30000
        }
      }
    }
    ```

    | Option           | Description                              |
    | ---------------- | ---------------------------------------- |
    | `imageLocators`  | CSS selectors for the CAPTCHA image      |
    | `inputLocators`  | CSS selectors for the answer input field |
    | `submitLocators` | CSS selectors for the submit button      |
  </Tab>

  <Tab title="Text CAPTCHAs">
    For text-based challenges (questions or puzzles):

    ```json theme={null}
    {
      "headful": true,
      "stealthMode": {
        "enabled": true
      },
      "captchaSolver": {
        "enabled": true,
        "text": {
          "enabled": true,
          "labelLocators": ["#captcha-question", ".challenge-text"],
          "inputLocators": ["#answer-input", ".captcha-answer"],
          "submitLocators": ["#verify-button", "button.submit"]
        },
        "settings": {
          "autoSolve": true,
          "solveDelay": 2000,
          "maxRetries": 3,
          "timeout": 30000
        }
      }
    }
    ```

    | Option           | Description                              |
    | ---------------- | ---------------------------------------- |
    | `labelLocators`  | CSS selectors for the challenge text     |
    | `inputLocators`  | CSS selectors for the answer input field |
    | `submitLocators` | CSS selectors for the submit button      |
  </Tab>
</Tabs>

### Settings reference

| Setting      | Default | Description                                           |
| ------------ | ------- | ----------------------------------------------------- |
| `autoSolve`  | `true`  | Automatically solve detected CAPTCHAs                 |
| `solveDelay` | `2000`  | Milliseconds to wait before solving (more human-like) |
| `maxRetries` | `3`     | Number of solve attempts before failing               |
| `timeout`    | `30000` | Maximum time (ms) to wait for solve                   |

<Tip>
  Increase `solveDelay` if websites detect bot-like behavior. A small delay
  makes automation appear more human.
</Tip>

### Helper methods

Control CAPTCHA solving with runtime helper methods. Wait for CAPTCHAs to resolve, subscribe to status updates, or pause the solver during automation.

**Quick example:**

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from intuned_runtime.captcha import wait_for_captcha_solve
    from intuned_browser import go_to_url

    await go_to_url(page=page, url="https://example.com")
    await wait_for_captcha_solve(page=page, timeout_s=120.0)

    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { waitForCaptchaSolve } from '@intuned/runtime';
    import { goToUrl } from '@intuned/browser';

    await goToUrl({ page, url: "https://example.com" });
    await waitForCaptchaSolve(page, { timeoutInMs: 120000 });
    ```
  </Tab>
</Tabs>

For complete documentation including all helper methods, parameters, and usage patterns, see the CAPTCHA helpers reference for [Python](/main/05-references/runtime-sdk-python/captcha-helpers) or [TypeScript](/main/05-references/runtime-sdk-typescript/captcha-helpers).

<Tip>
  If navigation or a button click may trigger the challenge, prefer the
  wrapper-style helpers so Intuned can wait for the page to settle before it
  checks solve status.
</Tip>

### Important considerations

* **Selector accuracy**—For custom and text CAPTCHAs, test selectors in browser console before deploying
* **Timeout settings**—Complex CAPTCHAs need higher timeouts
* **Service limits**—Some sites limit CAPTCHA attempts. Monitor solve rates to avoid additional blocks

<Tip>
  Use the [selector agent](/main/02-features/online-ide#selector-agent) to
  generate reliable selectors for custom and text CAPTCHA elements.
</Tip>

## Best practices

* **Start simple**: Enable features incrementally. First test your automation without protection, then add features as needed.
* **Keep dependencies updated**: Upgrade to the latest Playwright version. Stealth mode works best with newer versions, as updates include improved fingerprint spoofing and compatibility with the latest detection methods.
* **Use residential proxies sparingly**: Due to traffic-based billing, reserve residential proxies for websites that definitely block datacenter proxies.
* **Combine with other strategies**: These features work best alongside other automation best practices like rate limiting and respectful request patterns.

## Limitations

### Stealth mode

* Platform only—doesn't work with local CLI
* Requires Playwright v1.55+—upgrade to the latest version for best results
* New detection methods may emerge that stealth mode doesn't handle yet—report your case and we're happy to support it

### CAPTCHA solving

* Platform only—doesn't work with local CLI
* Must complete within configured timeout
* Some CAPTCHA types aren't supported—contact us if you encounter one

### Proxies

* Residential proxies have traffic-based billing
* Some sites block known proxy IP ranges
* Proxy speed varies by provider

## FAQs

<AccordionGroup>
  <Accordion title="Do I need all features together?">
    No. Each addresses different blocking mechanisms. Start with the simplest configuration and add features as needed. For most protected sites, headful + stealth mode is a good starting point.
  </Accordion>

  {" "}

  <Accordion title="Why don't stealth mode and CAPTCHA solving work locally (Intuned CLI)?">
    These features require the full Intuned platform environment to properly
    modify browser behavior. Use Intuned IDE to develop and test stealth-related
    features.
  </Accordion>

  <Accordion title="How much does stealth mode cost?">
    Stealth mode is included in Intuned platform plans at no additional cost. See [Plans and billing](/main/05-references/plans-and-billing) for details.
  </Accordion>

  <Accordion title="Why is my automation still getting blocked even with stealth mode enabled?">
    Websites vary widely in what they check. Some:

    * Use novel CAPTCHA types not yet supported
    * Check for multiple factors beyond fingerprint and IP
    * Have aggressive rate limiting
    * Require additional headers or request patterns

    Try combining stealth mode with proxies and headful mode. If you're still blocked, you might need to adjust your request patterns, add delays, or use a different proxy provider. We're continuously improving stealth mode to address new detection methods. Let us know if you encounter issues.
  </Accordion>

  {" "}

  <Accordion title="Does stealth mode slow down automation?">
    No significant impact. Startup time may increase slightly, but runtime
    performance is comparable to standard Playwright.
  </Accordion>

  {" "}

  <Accordion title="Can I use stealth mode with headless browsers?">
    Yes.
  </Accordion>

  <Accordion title="Should I use residential or datacenter proxies?">
    Start with datacenter proxies—they're cheaper. Only upgrade to residential if your target site actively blocks datacenter IPs. Monitor residential usage carefully due to per-GB billing.
  </Accordion>
</AccordionGroup>

## Related resources

<CardGroup cols={2}>
  <Card title="CAPTCHA Helpers (Python)" icon="python" href="/main/05-references/runtime-sdk-python/captcha-helpers">
    Complete runtime SDK reference for CAPTCHA helper methods in Python
  </Card>

  <Card title="CAPTCHA Helpers (TypeScript)" icon="js" href="/main/05-references/runtime-sdk-typescript/captcha-helpers">
    Complete runtime SDK reference for CAPTCHA helper methods in TypeScript
  </Card>

  <Card title="Intuned.json reference" icon="file-code" href="/main/05-references/intuned-json">
    Full configuration options for headful, stealthMode, and captchaSolver
  </Card>

  <Card title="CLI reference" icon="terminal" href="/main/05-references/cli/overview">
    CLI documentation including the --proxy flag
  </Card>

  <Card title="Playwright browsers support" icon="browser" href="/main/05-references/playwright-browsers-support">
    Playwright version requirements
  </Card>

  <Card title="Plans and billing" icon="credit-card" href="/main/05-references/plans-and-billing">
    Feature availability by plan
  </Card>
</CardGroup>