Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Stealth

Libretto's stealth browsers help hosted runs avoid bot detection.
Every Libretto Cloud browser runs in stealth mode. Hosted runs use residential proxies and managed browser fingerprints, so sessions look more like normal user traffic than bare automation.
Stealth also includes automatic CAPTCHA handling. Libretto Cloud cannot guarantee every challenge will clear, but common CAPTCHA and bot-check pages can resolve without a manual handoff.

Residential proxy locations

By default, Libretto Cloud uses a managed US residential proxy for each hosted browser. If the target site is location-sensitive, pass residential_proxy when you create a job, browser session, or schedule.
country is required and must be a two-letter ISO country code. You can refine US locations with state or zip, target a city with city, or target an ISP/network with asn.
curl -X POST "https://api.libretto.sh/v1/jobs/create" \
  -H "x-api-key: $LIBRETTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "workflow": "check-eligibility",
      "params": {
        "memberId": "12345"
      },
      "residential_proxy": {
        "country": "US",
        "state": "CA",
        "city": "san-francisco"
      }
    }
  }'
Supported fields:
  • country: two-letter country code, such as US.
  • state: two-letter US state code. Only supported with country: "US".
  • city: city slug without spaces.
  • zip: five-digit US ZIP code. Only supported with country: "US"; cannot be combined with city or state.
  • asn: network identifier such as AS7922; cannot be combined with city or state.
For recurring workflows, pass the same object to residential_proxy on /v1/schedules/create or /v1/schedules/update. To clear a schedule's configured proxy location, set residential_proxy to null on /v1/schedules/update.

Disable default proxy (direct egress)

Some sites fail through Kernel's default residential stealth proxy with errors like ERR_TUNNEL_CONNECTION_FAILED. For those targets, pass disable_default_proxy: true when you create a job, browser session, or schedule. Libretto Cloud flips the Kernel session to direct egress before any start_url navigation.
disable_default_proxy is Kernel-only and mutually exclusive with residential_proxy.
npx libretto cloud jobs create check-eligibility \
  --start-url 'https://example.com/dashboard' \
  --disable-default-proxy

Workflow behavior

On Libretto Cloud, if a workflow reaches a CAPTCHA, Cloudflare check, or similar interstitial, wait up to 2 minutes before treating it as blocked. That gives the hosted browser time to finish the provider-side solve and continue to the page your workflow expects.
After the wait, assert on the real page state with a URL or locator. This keeps failures clear when a challenge is not solved.
// Wait for hosted CAPTCHA solving; see https://libretto.sh/docs/libretto-cloud-hosting/stealth.
await page.waitForTimeout(120_000);
await page.getByRole("heading", { name: "Dashboard" }).waitFor();

Local and self-hosted runs

Stealth is included with Libretto Cloud and is also available through some other hosted browser providers. Local Chromium and self-hosted infrastructure do not include managed residential proxies or automatic CAPTCHA solving by default.
For self-hosted runs, set up your own external proxy and CAPTCHA-solving services, or solve challenges manually in a visible browser and continue from that state.
Powered byHolocron