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.

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

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

Residential proxies bill per GB of traffic. Monitor usage carefully to avoid unexpected charges.

Auto proxy (Intuned-managed)

If you don’t want to buy or manage your own proxy, set the proxy value to intuned://auto instead of a provider URL. Intuned resolves this to a working proxy from its managed pool at run time, health-checking candidates automatically. Set it once as a project default in intuned.json (see defaults.proxy), or from the CLI with intuned dev proxy set, which defaults to intuned://auto when no URL is given. You can also pass intuned://auto directly anywhere a proxy URL is accepted, including the run, AuthSession, and job-level proxy parameters below.

Auto proxy resolves automatically for platform runs and in Hosted projects (the online IDE), which provide a proxy for you. In Connected projects (the local CLI), set the INTUNED_PROXY_URL environment variable to a fixed proxy—otherwise no proxy is applied.

Proxy options

Anywhere a proxy is accepted for runs, AuthSessions, jobs, Web Tasks, or project defaults, pass either:

A proxy URL string (for example "http://username:password@domain:port" or "intuned://auto")
An object { url, regex? } for conditional URL-based proxying
A non-empty array of ordered proxy rule objects

Set timezone alongside proxy to make the browser clock match the proxy’s geography. Use a valid IANA timezone identifier such as "America/New_York". The same proxy formats work for job-level proxy and defaults.proxy in Intuned.json. You can also set a timezone from the CLI with intuned dev proxy set --timezone. Run level with timezone:

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: {
      url: "http://username:password@domain:port",
    },
    timezone: "America/New_York",
  });

  console.log(result);
}

run();

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={
            "url": "http://username:password@domain:port",
        },
        timezone="America/New_York",
      ),
    )

    # Handle response
    print(res)

Conditional URL proxying

Add regex to proxy only requests whose URL matches an RE2 pattern. Matching requests use the configured upstream proxy; nonmatching requests connect directly.

{
  "proxy": {
    "url": "http://username:password@domain:port",
    "regex": "^https://api\\.example\\.com/"
  }
}

Intuned matches against the request URL’s scheme, host, and percent-encoded pathname. Query strings and fragments are excluded. For example, https://ipinfo.io/json?token=secret is matched as https://ipinfo.io/json. Matching is unanchored unless you add ^ or $. RE2 does not support lookaround or backreferences. Conditional routing requires HTTPS inspection. When regex is set, Intuned creates an ephemeral certificate authority for the proxy process and configures its managed Chromium browser to trust that certificate. Without regex, Intuned uses standard HTTPS tunneling, does not terminate TLS, and does not pass a proxy certificate to the browser. You don’t need to install a certificate on the host system.

Ordered proxy rules

Use an array when different request URLs need different proxy pools. Intuned checks the rules from top to bottom and uses the first matching rule. If no rule matches, the request connects directly.

{
  "proxy": [
    {
      "url": [
        "http://username:password@proxy-1.example.com:8080",
        "http://username:password@proxy-2.example.com:8080"
      ],
      "regex": "^https://api\\.example\\.com/"
    },
    {
      "url": null,
      "regex": "^https://status\\.example\\.com/health$"
    },
    {
      "url": "http://username:password@fallback.example.com:8080"
    }
  ]
}

A rule without regex matches every remaining request, so later rules are unreachable. Set url to null to connect matching requests directly and stop evaluation. intuned://auto is not supported inside a rule array. For API retries and AuthSession creation attempts, Intuned randomly selects one URL from each rule’s pool. Each pool is selected independently, and the same URL can be selected on consecutive attempts. AuthSession checks stay on their saved selections. Recorder, Web Task, and other non-attempt flows use the first URL in each pool.

Configure proxies

Configure proxies at three levels. Use any format described in Proxy options. Run level—Use the proxy parameter when creating a Run:

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();

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)

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

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();

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)

Job level—Use the proxy field in job settings. See Job Settings.

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

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:

{
  "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 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

{
  "stealthMode": {
    "enabled": true
  }
}

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.

CAPTCHA solving

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

CAPTCHA is a general term for challenges that verify you’re human. This includes reCAPTCHA, hCaptcha, Cloudflare Turnstile, and similar services.

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.

Requirements

Headful mode required—Set headful to true
Stealth mode required—Set stealthMode.enabled to true
Online IDE or deployed runs—Doesn’t work in the local CLI runtime

Supported CAPTCHA types

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

Configure CAPTCHA solving

Enable Cloudflare
Specific providers
Custom image CAPTCHAs
TikTok
Text CAPTCHAs

{
  "headful": true,
  "stealthMode": {
    "enabled": true
  },
  "captchaSolver": {
    "enabled": true,
    "cloudflare": {
      "enabled": true
    },
    "settings": {
      "autoSolve": true,
      "solveDelay": 2000,
      "maxRetries": 6,
      "timeout": 30000
    }
  }
}

{
  "headful": true,
  "stealthMode": {
    "enabled": true
  },
  "captchaSolver": {
    "enabled": true,
    "googleRecaptcha": {
      "enabled": true
    },
    "settings": {
      "autoSolve": true,
      "solveDelay": 2000,
      "maxRetries": 3,
      "timeout": 30000
    }
  }
}

For custom image-based CAPTCHAs, you must provide CSS selectors to identify the CAPTCHA elements:

{
  "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

{
  "headful": true,
  "stealthMode": {
    "enabled": true
  },
  "captchaSolver": {
    "enabled": true,
    "tiktok": {
      "enabled": true
    },
    "settings": {
      "autoSolve": true,
      "solveDelay": 2000,
      "maxRetries": 10,
      "timeout": 30000
    }
  }
}

TikTok CAPTCHAs appear as either a puzzle (slide a piece into place) or a rotate (spin an image to the correct angle). Both are solved automatically using the SadCaptcha API.

For text-based challenges (questions or puzzles):

{
  "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

Settings reference

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

Increase solveDelay if websites detect bot-like behavior. A small delay makes automation appear more human.

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:

Python
TypeScript

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)

import { waitForCaptchaSolve } from '@intuned/runtime';
import { goToUrl } from '@intuned/browser';

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

For complete documentation including all helper methods, parameters, and usage patterns, see the CAPTCHA helpers reference for Python or TypeScript.

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.

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

Use the selector agent to generate reliable selectors for custom and text CAPTCHA elements.

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

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.

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.

How much does stealth mode cost?

Stealth mode is included in Intuned platform plans at no additional cost. See Plans and billing for details.

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.

Does stealth mode slow down automation?

No significant impact. Startup time may increase slightly, but runtime performance is comparable to standard Playwright.

Can I use stealth mode with headless browsers?

Yes.

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.

CAPTCHA Helpers (Python)

Complete runtime SDK reference for CAPTCHA helper methods in Python

CAPTCHA Helpers (TypeScript)

Complete runtime SDK reference for CAPTCHA helper methods in TypeScript

Intuned.json reference

Full configuration options for headful, stealthMode, and captchaSolver

CLI reference

CLI documentation including the —proxy flag

Playwright browsers support

Playwright version requirements

Plans and billing

Feature availability by plan

​Overview

​Which features do you need?

​Proxies

​Proxy types

​Auto proxy (Intuned-managed)

​Proxy options

​Conditional URL proxying

​Ordered proxy rules

​Configure proxies

​Best practices

​Headful mode

​Enable headful mode

​Stealth mode

​Requirements

​Enable stealth mode

​CAPTCHA solving

​Requirements

​Supported CAPTCHA types

​Configure CAPTCHA solving

​Settings reference

​Helper methods

​Important considerations

​Best practices

​Limitations

​Stealth mode

​CAPTCHA solving

​Proxies

​FAQs

​Related resources

CAPTCHA Helpers (Python)

CAPTCHA Helpers (TypeScript)

Intuned.json reference

CLI reference

Playwright browsers support

Plans and billing

Overview

Which features do you need?

Proxies

Proxy types

Auto proxy (Intuned-managed)

Proxy options

Conditional URL proxying

Ordered proxy rules

Configure proxies

Best practices

Headful mode

Enable headful mode

Stealth mode

Requirements

Enable stealth mode

CAPTCHA solving

Requirements

Supported CAPTCHA types

Configure CAPTCHA solving

Settings reference

Helper methods

Important considerations

Best practices

Limitations

Stealth mode

CAPTCHA solving

Proxies

FAQs

Related resources