[DOCS/BUG] Browser automation tools (Playwright/Puppeteer) incompatible with web sandbox proxy

[maorcc]

Summary

Browser automation tools like Playwright, Puppeteer, and Selenium cannot run in the Claude Code web sandbox due to the security proxy not supporting HTTPS CONNECT tunneling. This is a fundamental architectural limitation that should be documented to save users time.

Environment

• Claude Code: Web sandbox (claude.ai/code)
• Tool: Playwright v1.49.1 with Chromium v140.0.7339.16
• Test Date: 2025-11-16

Problem Description

The web sandbox's security proxy provides network isolation by mediating all outbound traffic through an HTTP proxy (visible as HTTPS_PROXY environment variable with JWT-based authentication). However, this proxy does not support the HTTP CONNECT method required by browsers for HTTPS tunneling.

Why This Matters

• Browser automation tools (Playwright, Puppeteer, Selenium) require CONNECT tunneling to access HTTPS sites
• The current proxy architecture only supports direct HTTP requests (e.g., curl, requests library)
• Users may waste significant time trying to configure browser automation in the sandbox

Reproduction Steps

1. Install Playwright in web sandbox:

   uv run playwright install chromium
   

2. Run any Playwright script accessing HTTPS sites:

   from playwright.sync_api import sync_playwright
   
   with sync_playwright() as p:
       browser = p.chromium.launch(headless=True)
       page = browser.new_page()
       page.goto('https://example.com')  # Fails here
       browser.close()
   

3. Result: ERR_TUNNEL_CONNECTION_FAILED

Error Messages Encountered

• net::ERR_TUNNEL_CONNECTION_FAILED - Most common (HTTPS sites)
• net::ERR_NO_SUPPORTED_PROXIES - When credentials in proxy URL
• HTTP 401 - When testing HTTP (not HTTPS) sites with JWT auth

Technical Analysis

What Works ✅

• HTTP tools like curl, requests, httpx (direct requests)
• Playwright installation
• All non-browser automation

What Doesn't Work ❌

• Any browser (Chromium, Firefox, WebKit) accessing HTTPS sites
• Playwright, Puppeteer, Selenium browser automation
• Any tool requiring CONNECT tunneling

Root Cause

From Anthropic's sandboxing docs:

"Network isolation: All outbound internet traffic passes through a proxy for security and abuse prevention purposes."

The security proxy:

• Uses JWT-based authentication in URL format
• Supports direct HTTP/HTTPS requests (standard proxy behavior)
• Does NOT support HTTP CONNECT method (browser tunneling)

This is by design for security, but creates incompatibility with browser automation.

Proposed Solutions

Option 1: Documentation (Immediate) ⭐

Add to sandbox documentation:

Browser Automation Limitations: Browser automation tools (Playwright, Puppeteer, Selenium) are not supported in the web sandbox environment. The security proxy does not support HTTPS CONNECT tunneling required by browsers. For web scraping, use HTTP libraries (requests, httpx) with HTML parsing (BeautifulSoup, lxml) instead, or run browser automation locally.

Option 2: Feature Enhancement (Future)

• Add CONNECT support to sandbox proxy (security implications to evaluate)
• Provide alternative browser automation pathway
• Offer Playwright MCP integration that works within sandbox constraints

Option 3: Workaround Guidance

Document recommended alternatives:

• Use requests + BeautifulSoup for HTML scraping
• Use httpx with async support
• Run browser automation locally, import results to sandbox

Impact

User Experience:

• Users attempting browser automation waste hours debugging
• No clear error message indicating architectural limitation
• Documentation doesn't mention this restriction

Use Cases Affected:

• Web scraping jobs
• End-to-end testing
• Screenshot/PDF generation
• Form automation

Related Issues

• #2256 - Tunnel proxy issues (corporate proxies)
• #1383 - Playwright MCP failures
• #5636 - Browser automation tools failing to launch

Recommendation

At minimum, update documentation to clearly state browser automation tools won't work in web sandbox and suggest alternatives. This would save users significant debugging time and set proper expectations.

---

Category: Documentation / Known Limitation Priority: Medium (affects user experience, not a critical bug) Effort: Low (documentation update) to High (architectural change)

[ian-klopper]

Adding my use case: I want cloud agents to test preview deployments (e.g., Vercel previews) using Browserbase/Stagehand before committing. Even though Browserbase runs browsers remotely, agents still need WebSocket/CDP connections to control them - which gets blocked by the current proxy. This workflow works locally but not in web sessions, which defeats the purpose of autonomous cloud agents.

[iSuslov]

In fact very important issue. Does anyone has an elegant workaround?

[KingMob]

I'm unable to run my automated Playwright tests in the sandbox, despite excluding the commands used.

I'm going to have to stop using the sandbox for this atm, which means my alternatives are either more dangerous, or more annoying.