# Browser

**Page:** kit/browser

[Download Raw Markdown](./kit/browser.md)

---

**Chrome-as-a-service.** Hoody Browser gives you HTTP control over Chromium instances—start browsers, navigate pages, evaluate JavaScript, manage tabs, and capture DevTools URLs. Perfect for web scraping, automated testing, screenshot services, and AI-driven web interaction.


**Traditional**: Install Puppeteer/Playwright locally, manage Chrome binaries, handle headless mode.

**Hoody Browser**: HTTP API to control browser instances. No installation. Works from any language or tool that speaks HTTP.

- Start/stop/restart browser instances
- Browse URLs and evaluate JavaScript
- Full Chrome DevTools Protocol access via WebSocket
- Multiple concurrent instances with different configurations
- Fingerprint profiles for browser emulation


## What You Can Do

- **Instance Management** - Start, stop, restart isolated browser instances
- **Page Navigation** - Browse URLs and get page content
- **JavaScript Execution** - Evaluate JS in browser context via HTTP
- **Tab Management** - List and manage browser tabs
- **DevTools Access** - Get WebSocket URL for Chrome DevTools Protocol
- **Fingerprinting** - Configure user agent, viewport, geolocation, locale
- **Health Monitoring** - Track server metrics and instance health
- **Multiple Instances** - Run concurrent browsers on different ports

## API Endpoints Summary

All endpoints accessed relative to your Browser service URL:
```
https://PROJECT_ID-CONTAINER_ID-browser-1.SERVER.containers.hoody.icu
```

**Instance Management**:
- [`GET /start`](/api/browser/instance-management/) - Create or retrieve browser instance
- [`GET /stop`](/api/browser/instance-management/) - Stop browser instance
- [`GET /restart`](/api/browser/instance-management/) - Restart browser instance

**Browser Interaction**:
- [`GET /browse?url=...`](/api/browser/interaction/) - Navigate to URL (returns page content)
- [`POST /browse`](/api/browser/interaction/) - Navigate with POST body options
- [`GET /eval?script=...`](/api/browser/interaction/) - Evaluate JavaScript script
- [`POST /eval`](/api/browser/interaction/) - Evaluate JavaScript with POST body

**Page Content & Export**:
- [`GET /html`](/api/browser/interaction/) - Get page HTML content
- [`GET /text`](/api/browser/interaction/) - Get page text content
- [`GET /screenshot`](/api/browser/interaction/) - Take a screenshot of the page
- [`GET /pdf`](/api/browser/interaction/) - Export page as PDF

**Cookies**:
- [`GET /cookies`](/api/browser/control/) - Get browser cookies
- [`POST /cookies`](/api/browser/control/) - Set browser cookies
- [`DELETE /cookies`](/api/browser/control/) - Clear browser cookies

**Introspection & Control**:
- [`GET /metadata`](/api/browser/control/) - Get instance metadata and DevTools URL
- [`GET /tabs`](/api/browser/control/) - List browser tabs
- [`POST /tab/close`](/api/browser/control/) - Close a browser tab
- [`GET /devtools-url`](/api/browser/control/) - Get DevTools WebSocket URL
- [`GET /shutdown`](/api/browser/control/) - Shutdown browser instance

**Logs & History**:
- [`GET /console`](/api/browser/health/) - Get browser console logs
- [`GET /network`](/api/browser/health/) - Get network request/response logs
- [`GET /history`](/api/browser/health/) - Query browsing history
- [`DELETE /history`](/api/browser/health/) - Delete browsing history

**Health & Metrics**:
- [`GET /api/v1/browser/health`](/api/browser/health/) - Service health check
- [`GET /metrics`](/api/browser/health/) - Server performance metrics

## Quick Start


  
    ```bash
    # Start a browser instance
    hoody browser start -c <container-id> --browser-id "main"

    # Navigate to a URL
    hoody browser navigate-post -c <container-id> --browser-id "main" --url "https://example.com"

    # Execute JavaScript
    hoody browser eval-post -c <container-id> --browser-id "main" --script "document.title"

    # Take a screenshot
    hoody browser screenshot -c <container-id> --browser-id "main"

    # List open tabs
    hoody browser tabs list -c <container-id> --browser-id "main"
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/hoody-sdk';

    const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });
    const containerClient = await client.withContainer({ id: CONTAINER_ID, project_id: PROJECT_ID, server: SERVER });

    const BROWSER_ID = 'default';

    // Start browser instance
    const instance = await containerClient.browser.instances.start({ browser_id: BROWSER_ID });

    // Navigate to URL
    const page = await containerClient.browser.interaction.browse({
      browser_id: BROWSER_ID,
      url: 'https://example.com',
    });

    // Execute JavaScript
    const result = await containerClient.browser.interaction.evalPost(
      { script: 'document.title' },
      { browser_id: BROWSER_ID },
    );

    // Take screenshot
    const screenshot = await containerClient.browser.interaction.takeScreenshot({ browser_id: BROWSER_ID });

    // List tabs
    const tabs = await containerClient.browser.introspection.listTabs({ browser_id: BROWSER_ID });
    ```
  
  
    ```bash
    # Start browser instance
    curl "https://PROJECT-CONTAINER-browser-1.SERVER.containers.hoody.icu/start?browser_id=default"

    # Navigate to URL
    curl "https://PROJECT-CONTAINER-browser-1.SERVER.containers.hoody.icu/browse?browser_id=default&url=https://example.com"

    # Execute JavaScript
    curl "https://PROJECT-CONTAINER-browser-1.SERVER.containers.hoody.icu/eval?browser_id=default&script=document.title"

    # List tabs
    curl "https://PROJECT-CONTAINER-browser-1.SERVER.containers.hoody.icu/tabs?browser_id=default"
    ```
  


**1. Start a browser instance:**



Returns instance metadata including the `webSocketDebuggerUrl` for Chrome DevTools Protocol access.

**2. Navigate to a page:**



**3. Execute JavaScript on the page:**



**4. List open tabs:**



## Browser Configuration

### Fingerprint Profiles

Configure browser identity for web scraping or testing:



**Available configuration:**
- **User Agent** - Custom browser identification string
- **Viewport** - Screen size and device pixel ratio
- **Geolocation** - Latitude/longitude spoofing
- **Locale & Timezone** - Language and time settings
- **Chromium Version** - Select specific Chrome version (`stable`, `beta`, `dev`, `canary`, or exact version)

### Multiple Instances

Run concurrent browser instances using different `browser_id` values:

```bash
# Start first instance
curl "https://PROJECT_ID-CONTAINER_ID-browser-1.SERVER.containers.hoody.icu/start?browser_id=scraper"

# Start second instance
curl "https://PROJECT_ID-CONTAINER_ID-browser-1.SERVER.containers.hoody.icu/start?browser_id=testing"

# Each instance is addressed by its browser_id
curl "https://PROJECT_ID-CONTAINER_ID-browser-1.SERVER.containers.hoody.icu/browse?browser_id=scraper&url=https://example.com"
curl "https://PROJECT_ID-CONTAINER_ID-browser-1.SERVER.containers.hoody.icu/browse?browser_id=testing&url=https://example.org"
```

Each instance is isolated with its own tabs, cookies, and state.

## Chrome DevTools Protocol

Get the WebSocket URL for direct CDP access:



Use the returned URL with Puppeteer, Playwright, or any CDP client:

```javascript
const puppeteer = require('puppeteer-core');

// Connect to Hoody Browser instance
const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://...'  // URL from /devtools-url
});

const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png' });
```

## Use Cases

- **Web Scraping** - Extract data from websites via HTTP API
- **Automated Testing** - Run E2E tests against web applications
- **Screenshot Services** - Capture webpage screenshots on demand
- **AI Web Interaction** - Let AI agents browse and interact with web pages
- **PDF Generation** - Render HTML to PDF via Chrome's print functionality
- **Performance Monitoring** - Audit web performance metrics

## What's Next

- [Browser Instance Management API](/api/browser/instance-management/) - Start, stop, restart instances
- [Browser Interaction API](/api/browser/interaction/) - Navigate and evaluate JavaScript
- [Browser Control API](/api/browser/control/) - Metadata, tabs, and DevTools
- [Browser Health API](/api/browser/health/) - Metrics and monitoring
- [cURL Service](/kit/curl/) - For simpler HTTP requests without a browser
- [Exec Service](/kit/exec/) - Execute scripts that orchestrate browser automation