Stealth — Anti-Bot Detection for AI Agents

Three layers, applied in order. Most blocks are solved at Layer 1.

Quick Diagnostic

Run this first to understand the problem:

curl -s https://ipinfo.io/json | python3 -c "
import sys,json;d=json.load(sys.stdin)
org=d.get('org','')
h=d.get('privacy',{}).get('hosting') if 'privacy' in d else None
dc=h or any(x in org.lower() for x in ['digital','amazon','google','microsoft','azure','linode','vultr','hetzner','ovh','cloud'])
print(f'IP: {d[\"ip\"]} | Org: {org} | Datacenter: {dc}')
if dc: print('⚠️  Datacenter IP detected → Layer 1 (proxy) required')
else: print('✅ Residential IP — skip to Layer 2 or 3 if still blocked')
"

Block type reference

Layer 1: Residential Proxy

The #1 fix. Datacenter IPs are flagged instantly by Cloudflare, Akamai, PerimeterX, and most anti-bot systems. A residential proxy routes traffic through real ISP connections.

See references/proxy-setup.md for provider comparison and setup instructions.

Quick test after setup:

curl -x http://USER:PASS@HOST:PORT -s https://ipinfo.io/json | python3 -c "
import sys,json;d=json.load(sys.stdin)
print(f'Proxy IP: {d[\"ip\"]} | Org: {d.get(\"org\")}')
"

Org should show an ISP (Comcast, Verizon, AT&T), not a cloud provider.

Layer 2: CAPTCHA Solving

Never attempt CAPTCHAs yourself. You will fail, burn tokens, and trigger escalated challenges. Always use a solver service.

Critical routing rule: 2Captcha dropped hCaptcha support entirely in late 2025. Use CapSolver for hCaptcha.

See references/captcha-setup.md for provider setup, API integration code, and token injection.

Layer 3: Stealth Browser

When proxy alone isn't enough. Sites fingerprint headless browsers via navigator properties, WebGL, Canvas, and automation flags.

See references/browser-stealth.md for Playwright stealth config, header templates, and anti-fingerprinting.

Troubleshooting