# Kiwi Browser API — Session Recipe (May 7, 2026)

This is the exact working setup built during the session. It runs Chromium inside a Debian Docker container on ZimaOS (which has no package manager and a read-only rootfs).

## One-liner setup

```bash
# Run this from the server shell (or via Hermes terminal)
sudo docker run -d --name kiwi-browser --restart unless-stopped \
  -p 0.0.0.0:30000:3000 \
  kiwi-browser:v1 \
  bash -c 'cd /app && python3 server.py > /app/server.log 2>&1'
```

## What the setup gives you

- Chromium 148+ running inside Debian Bookworm container
- HTTP API on `http://127.0.0.1:30000`
- Health endpoint, page visit, screenshot capture

## API endpoints

### GET /health
```bash
curl http://localhost:30000/health
# → {"status": "ok", "browser": "/usr/bin/chromium"}
```

### POST /visit
```bash
# Visit a page
DATA=$(printf '%s' '{"url": "https://www.amazon.de/dp/B0CRLJ9V5L", "selector": "a-offscreen"}')
curl -X POST http://localhost:30000/visit \
  -H "Content-Type: application/json" \
  -d "$DATA"
```

**Response fields:**
- `success` — boolean, true if page loaded
- `title` — page title
- `html_preview` — first 2000 chars of HTML
- `extracted` — text matching the optional selector
- `error` — stderr if Chromium failed

### POST /screenshot
```bash
# Screenshot a page
DATA=$(printf '%s' '{"url": "https://www.amazon.de/dp/B0CRLJ9V5L"}')
RESULT=$(curl -s -X POST http://localhost:30000/screenshot \
  -H "Content-Type: application/json" \
  -d "$DATA")

# Extract and save base64 image
echo "$RESULT" | python3 -c 'import json, sys, base64; d=json.load(sys.stdin); open("/tmp/screenshot.png","wb").write(base64.b64decode(d["screenshot_base64"]))'
```

## How to build the Kiwi-Browser image from scratch

```bash
# Step 1: Pull Debian slim (reliable, ~30MB)
sudo docker run -d --name browser-build debian:bookworm-slim sleep 3600

# Step 2: Install Chromium + Python
sudo docker exec browser-build apt-get update -qq
sudo docker exec browser-build apt-get install -y -qq --no-install-recommends chromium python3

# Step 3: Verify
sudo docker exec browser-build chromium --version

# Step 4: Add the Python API server (server.py must be built first)
# See templates/kiwi-browser-server.py
sudo docker cp kiwi-browser-server.py browser-build:/app/server.py

# Step 5: Commit to local image
sudo docker stop browser-build
sudo docker commit browser-build kiwi-browser:v1
sudo docker rm browser-build
```

## Known limits

- Amazon DE blocks headless Chromium aggressively (returns "Page Not Found" or captcha).
- YouTube works for basic page loads but heavy JS may need longer timeouts.
- The container needs `--restart unless-stopped` or a systemd/Cron restart rule.

## ZimaOS prerequisites

- User `az-a` must have `sudo` privileges for `docker` commands.
- The `docker` binary must be usable: `sudo usermod -aG docker az-a` (then re-login).