<!--
hoody-browser Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-06T18:32:30.770Z
Model: mimo-v2.5-pro
Mode: http


Tokens: 6444

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-browser Subskill

## Overview

**hoody-browser** provides headless Chrome browser automation accessible via HTTP REST API. It enables programmatic web browsing, screenshot capture, JavaScript evaluation, PDF generation, and page content extraction—all without requiring local browser installations.

### When to Use

- **Web scraping**: Extract text, HTML, or structured data from web pages
- **Screenshot automation**: Capture visual snapshots of pages for monitoring or archiving
- **PDF generation**: Convert web pages to PDF documents
- **JavaScript execution**: Run custom scripts in a browser context
- **Cookie/session management**: Maintain authenticated browsing sessions
- **Network inspection**: Monitor HTTP requests and responses
- **Console debugging**: Capture browser console output for troubleshooting

### How It Fits Into Hoody

hoody-browser follows the Hoody Kit service philosophy: **browser automation accessible via HTTP**. Each browser instance is isolated, stateful, and identified by a `browser_id`. The service runs as a containerized headless Chrome process, accessible through the Hoody Proxy routing system with automatic SSL and authentication.

### Service Architecture

- **Instance-based**: Each `browser_id` maps to an isolated browser process
- **Stateful**: Tabs, cookies, and navigation persist within an instance
- **RESTful**: All operations are HTTP GET/POST/DELETE requests
- **Buffered introspection**: Console and network logs retain the last 500 entries

### Base URL Pattern

```
https://{projectId}-{containerId}-browser-{serviceId}.{node}.containers.hoody.icu
```

All paths below are appended to this base URL exactly as shown. Do **not** add additional prefixes.

---

## Common Workflows

### 1. Browser Lifecycle Management

**Create a browser instance:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/start?browser_id=my-browser"
```

Response includes instance metadata confirming the browser is ready.

**Check instance metadata:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/metadata?browser_id=my-browser"
```

**Stop a browser instance:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/stop?browser_id=my-browser"
```

**Restart with fresh state:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/restart?browser_id=my-browser"
```

**Shutdown and release resources:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/shutdown?browser_id=my-browser"
```

### 2. Navigate and Capture Screenshots

**Navigate to a URL (GET):**

```
curl -s "https://BROWSER_BASE/api/v1/browser/browse?browser_id=my-browser&url=https://example.com"
```

**Navigate to a URL (POST):**

```
curl -s -X POST "https://BROWSER_BASE/api/v1/browser/browse" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'
```

**Capture screenshot of current page:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/screenshot?browser_id=my-browser"
```

**Navigate and screenshot in one step:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/screenshot?browser_id=my-browser&url=https://example.com"
```

### 3. Extract Page Content

**Get full HTML:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/html?browser_id=my-browser"
```

**Get visible text only:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/text?browser_id=my-browser"
```

**Generate PDF:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/pdf?browser_id=my-browser"
```

### 4. Execute JavaScript

**Evaluate script (GET):**

```
curl -s "https://BROWSER_BASE/api/v1/browser/eval?browser_id=my-browser&script=document.title"
```

**Evaluate script (POST) for complex code:**

```
curl -s -X POST "https://BROWSER_BASE/api/v1/browser/eval" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 5. Cookie Management

**Get all cookies:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/cookies?browser_id=my-browser"
```

**Set cookies:**

```
curl -s -X POST "https://BROWSER_BASE/api/v1/browser/cookies" \
  -H "Content-Type: application/json" \
  -d '{
    "cookies": [
      {
        "name": "session_id",
        "value": "abc123",
        "url": "https://example.com"
      }
    ]
  }'
```

**Clear all cookies:**

```
curl -s -X DELETE "https://BROWSER_BASE/api/v1/browser/cookies?browser_id=my-browser"
```

### 6. Tab Management

**List open tabs:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/tabs?browser_id=my-browser"
```

**Close a specific tab:**

```
curl -s -X POST "https://BROWSER_BASE/api/v1/browser/tab/close" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 7. Debugging and Inspection

**Get console logs:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/console?browser_id=my-browser"
```

**Get network logs:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/network?browser_id=my-browser"
```

**Get DevTools connection URL:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/devtools-url?browser_id=my-browser"
```

---

## Advanced Operations

### Multi-Step Workflow: Authenticated Scraping

This workflow demonstrates logging into a site, then extracting protected content.

**Step 1 — Start browser and navigate to login page:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/start?browser_id=scraper-1"

curl -s "https://BROWSER_BASE/api/v1/browser/browse?browser_id=scraper-1&url=https://example.com/login"
```

**Step 2 — Execute login script:**

```
curl -s -X POST "https://BROWSER_BASE/api/v1/browser/eval" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Step 3 — Verify login by checking page text:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/text?browser_id=scraper-1"
```

**Step 4 — Navigate to protected page and extract data:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/browse?browser_id=scraper-1&url=https://example.com/dashboard"

curl -s "https://BROWSER_BASE/api/v1/browser/html?browser_id=scraper-1"
```

**Step 5 — Cleanup:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/shutdown?browser_id=scraper-1"
```

### Multi-Step Workflow: Screenshot Monitoring

Capture screenshots of multiple pages for visual regression or uptime monitoring.

```
# Start instance
curl -s "https://BROWSER_BASE/api/v1/browser/start?browser_id=monitor-1"

# Capture page 1
curl -s "https://BROWSER_BASE/api/v1/browser/screenshot?browser_id=monitor-1&url=https://example.com"

# Capture page 2 (reuses same instance)
curl -s "https://BROWSER_BASE/api/v1/browser/screenshot?browser_id=monitor-1&url=https://example.com/about"

# Cleanup
curl -s "https://BROWSER_BASE/api/v1/browser/shutdown?browser_id=monitor-1"
```

### Error Recovery Patterns

**Instance may have crashed — restart before proceeding:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/restart?browser_id=my-browser"
```

**Check health before operations:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/api/v1/browser/health"
```

**Verify instance exists before interaction:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/metadata?browser_id=my-browser"
```

If metadata returns an error, call `/start` to create a new instance.

### Performance Considerations

- **Reuse instances**: Create once with `/start`, perform multiple operations, then `/shutdown`
- **Close unused tabs**: Use `/tab/close` to free memory from tabs no longer needed
- **Use `/text` over `/html`**: When you only need visible content, text extraction is faster and smaller
- **Buffer limits**: Console and network logs retain only the last 500 entries; retrieve them before they overflow
- **Timeout awareness**: Set `--max-time` appropriately; page loads and PDF generation can be slow

### Browsing History Management

**Retrieve browsing history:**

```
curl -s "https://BROWSER_BASE/api/v1/browser/history"
```

**Delete browsing history:**

```
curl -s -X DELETE "https://BROWSER_BASE/api/v1/browser/history"
```

Note: History is recorded for all navigations including API-triggered and manual browsing. History reads from persistent storage.

---

## Quick Reference

### Essential Endpoints

| Operation | Method | Path |
|-----------|--------|------|
| Start instance | GET | `/api/v1/browser/start?browser_id={id}` |
| Stop instance | GET | `/api/v1/browser/stop?browser_id={id}` |
| Restart instance | GET | `/api/v1/browser/restart?browser_id={id}` |
| Shutdown instance | GET | `/api/v1/browser/shutdown?browser_id={id}` |
| Navigate | GET | `/api/v1/browser/browse?browser_id={id}&url={url}` |
| Screenshot | GET | `/api/v1/browser/screenshot?browser_id={id}` |
| Get HTML | GET | `/api/v1/browser/html?browser_id={id}` |
| Get text | GET | `/api/v1/browser/text?browser_id={id}` |
| Evaluate JS | GET | `/api/v1/browser/eval?browser_id={id}&script={js}` |
| Get cookies | GET | `/api/v1/browser/cookies?browser_id={id}` |
| Set cookies | POST | `/api/v1/browser/cookies` |
| Clear cookies | DELETE | `/api/v1/browser/cookies?browser_id={id}` |
| List tabs | GET | `/api/v1/browser/tabs?browser_id={id}` |
| Close tab | POST | `/api/v1/browser/tab/close` |
| Console logs | GET | `/api/v1/browser/console?browser_id={id}` |
| Network logs | GET | `/api/v1/browser/network?browser_id={id}` |
| Metadata | GET | `/api/v1/browser/metadata?browser_id={id}` |
| Health check | GET | `/api/v1/browser/api/v1/browser/health` |
| DevTools URL | GET | `/api/v1/browser/devtools-url?browser_id={id}` |
| Generate PDF | GET | `/api/v1/browser/pdf?browser_id={id}` |
| History | GET | `/api/v1/browser/history` |
| Delete history | DELETE | `/api/v1/browser/history` |

### Required Parameters

Nearly all endpoints require `browser_id` as a query parameter. Exceptions:
- `/api/v1/browser/api/v1/browser/health` — no parameters
- `/api/v1/browser/history` — no required parameters
- `/api/v1/browser/eval` (GET) — requires both `browser_id` and `script`

### Typical Workflow Sequence

```
/start → /browse → /screenshot or /html or /text → /shutdown
```

### Response Format

All endpoints return JSON. Health check follows the 9-field standardized contract. Instance operations return metadata objects. Content endpoints return the requested data directly or as base64-encoded binary (screenshots, PDFs).