# hoody-browser Subskill ## Overview **hoody-browser** provides headless Chrome browser automation accessible via HTTP REST API. It enables AI agents and applications to programmatically control web browsers — navigating pages, extracting content, executing JavaScript, capturing screenshots, and managing browser state — without requiring direct WebSocket connections to Chrome DevTools. ### When to Use - **Web scraping**: Extract structured data from dynamic JavaScript-rendered pages - **Screenshot capture**: Generate visual snapshots of web pages for verification or archiving - **PDF generation**: Convert web pages to PDF documents with configurable formatting - **Form automation**: Fill and submit web forms, handle authentication flows - **Testing & monitoring**: Verify page content, check for errors, validate DOM state - **Cookie/session management**: Maintain authenticated browsing sessions across requests ### Philosophy Fit hoody-browser embodies the Hoody principle of **infrastructure-as-API**. Rather than managing Chrome processes, installing Puppeteer, or configuring headless environments, agents interact with a clean HTTP interface. Each browser instance is isolated via `browser_id`, enabling multi-tenant parallel browsing. The service handles lifecycle management, resource cleanup, and inter-process communication automatically. ### Architecture ``` Agent → HTTP Request → hoody-proxy → hoody-browser → Headless Chrome (per instance) ``` Each browser instance is a separate Chrome child process. Instances are identified by a `browser_id` you provide at creation time. Resources are released when you explicitly stop or shutdown an instance. --- ## Common Workflows ### 1. Browser Lifecycle: Start → Use → Stop The fundamental pattern. Always start a browser instance before interacting with it, and stop it when done to release resources. ``` # Step 1: Start a browser instance (browser_id is required) curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/start?browser_id=my-session" ``` ``` { "status": "started", "browser_id": "my-session" } ``` ``` # Step 2: Verify the instance is running curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/metadata?browser_id=my-session" ``` ``` { "session": { "id": "my-session" }, "browser": { "name": "Chrome", "version": "120.0.0.0" }, "os": { "name": "Linux" } } ``` ``` # Step 3: Stop the instance when done curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/stop?browser_id=my-session" ``` ``` { "status": "stopped" } ``` ### 2. Navigate and Capture Screenshot Navigate to a URL and capture a visual screenshot. The `screenshot` endpoint can combine navigation and capture in a single call. ``` # Navigate to a URL and capture screenshot in one step curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/screenshot?browser_id=my-session&url=https://example.com" -o page.png ``` ``` # Alternatively: navigate first, then screenshot current page curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/browse?browser_id=my-session&url=https://example.com" ``` ``` { "status": "navigated", "url": "https://example.com" } ``` ``` # Capture screenshot of the current page (no url parameter = capture current state) curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/screenshot?browser_id=my-session" -o current-page.png ``` ### 3. Extract Page Content Retrieve HTML or visible text content from the active page. ``` # Get full HTML of the active page curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/html?browser_id=my-session" ``` ```html ... ``` ``` # Get visible text only (excludes scripts, styles, hidden elements) curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/text?browser_id=my-session" ``` ``` Example Domain This domain is for use in illustrative examples in documents. ``` ### 4. Execute JavaScript Run custom JavaScript in the page context. Use GET for simple scripts, POST for longer or complex scripts. ``` # Execute a simple script via GET (script as query parameter) curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/eval?browser_id=my-session&script=document.title" ``` ``` { "result": "Example Domain" } ``` ``` # Execute a complex script via POST (script in request body) curl -s -X POST "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/eval" \ -H "Content-Type: application/json" \ -d '{ "browser_id": "my-session", "script": "document.querySelectorAll(\"a\").length" }' ``` ``` { "result": 1 } ``` ### 5. Manage Cookies Add, retrieve, and clear cookies for authenticated browsing sessions. ``` # Set a cookie before navigating curl -s -X POST "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/cookies" \ -H "Content-Type: application/json" \ -d '{ "browser_id": "my-session", "cookies": [ { "name": "session_token", "value": "abc123", "url": "https://example.com" } ] }' ``` ``` # Retrieve all cookies curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/cookies?browser_id=my-session" ``` ``` # Clear all cookies curl -s -X DELETE "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/cookies?browser_id=my-session" ``` ### 6. Tab Management List, create, and close tabs within a browser instance. ``` # List all open tabs curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/tabs?browser_id=my-session" ``` ``` { "tabs": [ { "tabId": "1", "url": "https://example.com", "title": "Example Domain", "active": true } ] } ``` ``` # Open a new tab by browsing to a new URL curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/browse?browser_id=my-session&url=https://example.org" ``` ``` # Close a specific tab by tabId curl -s -X POST "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/tab/close" \ -H "Content-Type: application/json" \ -d '{ "browser_id": "my-session", "tabId": "1" }' ``` --- ## Advanced Operations ### 7. Generate PDF from Web Page Navigate to a page and generate a PDF with custom formatting. ``` # Generate PDF of current page curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/pdf?browser_id=my-session" -o report.pdf ``` ### 8. Debugging: Console and Network Logs Inspect browser console output and network traffic for debugging automation scripts. ``` # View buffered console messages (last 500 entries) curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/console?browser_id=my-session" ``` ``` { "entries": [ { "type": "log", "text": "Page loaded", "timestamp": 1700000000000 }, { "type": "error", "text": "Failed to load resource", "timestamp": 1700000001000 } ] } ``` ``` # View buffered network requests (last 500 entries) curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/network?browser_id=my-session" ``` ``` { "entries": [ { "method": "GET", "url": "https://example.com/", "status": 200 }, { "method": "GET", "url": "https://example.com/style.css", "status": 200 } ] } ``` ### 9. Browsing History Management Query and manage persistent browsing history across sessions. ``` # Get browsing history (paginated) curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/history" ``` ``` # Delete all history curl -s -X DELETE "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/history" ``` ### 10. Access Chrome DevTools Get the DevTools WebSocket URL for advanced debugging or direct protocol access. ``` curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/devtools-url?browser_id=my-session" ``` ``` { "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/...", "devtoolsUrl": "http://127.0.0.1:9222/json/version" } ``` ### 11. Browser Restart Restart an instance with the same configuration — useful when a page has corrupted state. ``` curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/restart?browser_id=my-session" ``` ``` { "status": "restarted", "browser_id": "my-session" } ``` ### Error Recovery Patterns **Instance not found**: If an endpoint returns an error indicating no active browser, call `/start` first with your `browser_id`. **Page crash**: Call `/restart` to reinitialize the browser instance. All open tabs and cookies will be lost. **Stale content**: Navigate away and back, or use `/eval` to force `location.reload()`: ``` curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/eval?browser_id=my-session&script=location.reload()" ``` **Resource cleanup**: Always call `/stop` or `/shutdown` when finished to prevent orphaned Chrome processes. ### Performance Considerations - Each `browser_id` spawns a separate Chrome process. Limit concurrent instances based on available memory. - Use `/browse` with POST for navigating to URLs with complex payloads. - Console and network buffers hold the last 500 entries each — retrieve them before they rotate. - History is persisted to disk and survives instance restarts; use `/history` DELETE to clean up. --- ## Quick Reference ### Most Common Endpoints | Action | Method | Path | Required Params | |---|---|---|---| | Start browser | GET | `/api/v1/browser/start` | `browser_id` | | Navigate | GET | `/api/v1/browser/browse` | `browser_id`, `url` | | Screenshot | GET | `/api/v1/browser/screenshot` | `browser_id` | | Get HTML | GET | `/api/v1/browser/html` | `browser_id` | | Get text | GET | `/api/v1/browser/text` | `browser_id` | | Run JS | GET | `/api/v1/browser/eval` | `browser_id`, `script` | | Run JS (POST) | POST | `/api/v1/browser/eval` | `browser_id` (body: `script`) | | Stop browser | GET | `/api/v1/browser/stop` | `browser_id` | | Health check | GET | `/api/v1/browser/api/v1/browser/health` | — | ### Essential Parameters - **`browser_id`** (string, required): Your chosen identifier for the browser instance. Use consistent IDs to resume sessions. - **`url`** (string): Target URL for navigation endpoints. - **`script`** (string): JavaScript code to execute in page context. ### Typical Response Formats All responses are JSON. Successful operations return a status field or the requested data. The health endpoint follows the 9-field Hoody health contract. ### Service Health ``` curl -s "https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com/api/v1/browser/api/v1/browser/health" ``` ``` { "status": "healthy", "service": "hoody-browser", "version": "1.0.0" } ``` ### Container Discovery To discover the correct base URL for your browser service, refer to the **hoody-core SKILL.md** container discovery workflow. The base URL pattern is: ``` https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.com ``` All endpoint paths are appended directly to this base URL with **no additional prefix** beyond what appears in the endpoint inventory.