---
name: zimaos-camofox-browser
description: "Camofox-Browser als persistenten Docker-Dienst auf ZimaOS für Hermes-Browser-Automation einrichten und betreiben."
version: 1.0.0
author: Kiwi (Ahmed Zeyd Aytac)
tags: [zimaos, camofox, browser, docker, compose, hermes, anti-detection, persistence]
---

# ZimaOS Camofox Browser

Ziel: Auf dem ZimaOS-Server soll Browser-Automation für Hermes **immer** über einen lokalen Camofox-Browser-Container laufen — nicht über Webtop, nicht primär über linuxserver/chromium, nicht primär über Kasm und nicht primär über Browserless.

## Architekturstandard

1. **Camofox local mode** als Docker/Compose-Dienst auf ZimaOS bevorzugen.
2. Hermes verwendet seine nativen Browser-Tools über `CAMOFOX_URL`.
3. Hermes direkt auf ZimaOS-Host → `CAMOFOX_URL=http://127.0.0.1:9377`.
4. Hermes selbst in Docker → gemeinsames Docker-Netzwerk und `CAMOFOX_URL=http://camofox-browser:9377`.
5. **Persistence aktivieren**, damit Cookies, Logins, LocalStorage und Sessions über Neustarts erhalten bleiben.
6. noVNC nur zur Beobachtung oder manuellen MFA/CAPTCHA/Login-Hilfe; noVNC ist **nicht** die primäre Agentensteuerung.
7. Camofox-API nicht öffentlich ins WAN exponieren. Port 9377 an localhost oder nur an internes Docker-Netzwerk binden.
8. **Keinen `CAMOFOX_API_KEY` setzen**, solange Hermes' Camofox-Integration bei gesetztem Key 403-Probleme haben kann. Sicherheit stattdessen über Bind-Adresse, Firewall, Docker-Netzwerk, VPN oder SSH-Tunnel.
9. Für ZimaOS persistente Pfade unter `/DATA/AppData/camofox` verwenden. Keine fragilen Container ohne Volume.
10. Sessions nach Aufgaben: erst `browser.camofox.managed_persistence: true` prüfen, optional extern gemanagte Sessions mit `CAMOFOX_USER_ID`, `CAMOFOX_SESSION_KEY` und `CAMOFOX_ADOPT_EXISTING_TAB=true`.

## Referenz-Compose für ZimaOS

```yaml
services:
  camofox-browser:
    image: camofox-browser:local
    container_name: camofox-browser
    restart: unless-stopped
    ports:
      - "127.0.0.1:9377:9377"
      - "127.0.0.1:6080:6080"
    environment:
      CAMOFOX_PORT: "9377"
      ENABLE_VNC: "1"
      VNC_BIND: "0.0.0.0"
      VNC_RESOLUTION: "1920x1080"
      MAX_OLD_SPACE_SIZE: "2048"
    volumes:
      - /DATA/AppData/camofox:/root/.camofox
```

## Hermes-Konfiguration

### 1. `.env` — CAMOFOX_URL setzen

```bash
# In ~/.hermes/.env:
CAMOFOX_URL=http://127.0.0.1:9377
```

Bei Hermes-in-Docker stattdessen:
```bash
CAMOFOX_URL=http://camofox-browser:9377
```

### 2. `config.yaml` — managed persistence

```yaml
browser:
  camofox:
    managed_persistence: true
```

### 3. Browser-Toolset aktivieren

```bash
hermes tools enable browser
```

### 4. Hermes vollständig neu starten

Nach allen Änderungen muss Hermes komplett neu gestartet werden (Gateway-Restart oder CLI-Neustart).

## Verifikation

### Schritt 1: Camofox-Erreichbarkeit prüfen

```bash
curl -fsS http://127.0.0.1:9377/health
# oder einen anderen API-Endpunkt des Camofox-Servers
```

### Schritt 2: CAMOFOX_URL in .env prüfen

```bash
grep CAMOFOX_URL ~/.hermes/.env
```

### Schritt 3: Browser-Aufgabe + noVNC-Beobachtung

```bash
# noVNC über SSH-Tunnel:
ssh -L 6080:127.0.0.1:6080 user@zimaos
# Dann im Browser: http://localhost:6080
```

Starte eine Browser-Aufgabe in Hermes und beobachte über noVNC.

### Schritt 4: Persistenz-Test

1. Logge dich manuell auf einer Website ein.
2. Beende die Browser-Aufgabe.
3. Starte eine neue Browser-Aufgabe.
4. Prüfe, ob der Login erhalten bleibt.

### Schritt 5: Docker-Netzwerk-Fallback

Wenn Hermes in Docker läuft und `127.0.0.1` nicht funktioniert:
```bash
CAMOFOX_URL=http://camofox-browser:9377
```
im gemeinsamen Docker-Netzwerk verwenden.

## Build-Prozess (ZimaOS)

Da `jo-inc/camofox-browser` kein öffentliches Docker-Image hat, muss **lokal gebaut** werden.
ZimaOS hat kein `make` — die Schritte sind manuell:

### 1. Repo clonen + Assets downloaden

```bash
cd /tmp
git clone https://github.com/jo-inc/camofox-browser.git
cd camofox-browser
mkdir -p dist
curl -fSL "https://github.com/daijro/camoufox/releases/download/v135.0.1-beta.24/camoufox-135.0.1-beta.24-lin.x86_64.zip" -o dist/camoufox-x86_64.zip
curl -fSL "https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_linux" -o dist/yt-dlp-x86_64
```

### 2. Image bauen (mit VNC-Support)

Der Standard-Dockerfile hat **kein** `x11vnc`, `noVNC` oder `websockify`.
Ein angepasster Dockerfile wird benötigt. Siehe `references/build-dockerfile.md` für das vollständige Dockerfile.

```bash
DOCKER_BUILDKIT=1 docker build --no-cache \
  --build-arg ARCH=x86_64 \
  --build-arg CAMOUFOX_VERSION=135.0.1 \
  --build-arg CAMOUFOX_RELEASE=beta.24 \
  -t camofox-browser:135.0.1-x86_64 \
  -f /path/to/custom.Dockerfile .
```

### 3. VNC-Config für Camofox

VNC ist im Standard-Image **deaktiviert**. Config mit aktiviertem VNC als Volume mounten:

```json
{
  "id": "camofox-browser",
  "name": "Camofox Browser",
  "version": "1.6.0",
  "plugins": {
    "youtube": { "enabled": true },
    "persistence": { "enabled": true },
    "vnc": { "enabled": true, "resolution": "1920x1080" }
  }
}
```

Die Datei ins Compose-File einbinden (siehe Referenz-Compose).

### 4. Websockify nachinstallieren (im laufenden Container)

`websockify` fehlt im Python-Path des Containers und muss nachinstalliert werden:

```bash
docker exec camofox-browser pip3 install --break-system-packages websockify
# Oder im Dockerfile ergänzen: RUN pip3 install --break-system-packages websockify
```

### Compose-File starten

```bash
docker --config /tmp/docker-config compose -f /DATA/AppData/camofox-compose/docker-compose.yml up -d
```

**Wichtig:** Auf ZimaOS immer `DOCKER_CONFIG=/tmp/docker-config` setzen — `/root/.docker` ist read-only.

## Web-Research Patterns (new in this session)

When doing ad-hoc web research through Camofox, use this ordered fallback chain:

1. **Search with DuckDuckGo first — but use screenshot+vision, NOT the links endpoint.** Google frequently blocks Camofox/jina.ai with 429/CAPTCHA. DuckDuckGo (`https://duckduckgo.com/?q=...`) is far more tolerant of automated access, but it is a **JS-heavy SPA** — the `/tabs/:tabId/links` endpoint only returns navigation chrome (DuckDuckGo logo, filter tabs, settings links), NOT the actual search results. The working pattern: open DDG search in a Camofox tab → wait 3-4s for JS render → take screenshot → use `vision_analyze` to read result titles and URLs → then extract those URLs with jina.ai or open them directly. For `site:` restricted searches (e.g. `site:islamqa.info freemasonry`), this is the only reliable way to discover the correct answer URLs on JS-routed fatwa sites.
2. **Extract article text with r.jina.ai.** `curl -sL "https://r.jina.ai/<URL>" -H "Accept: text/plain"` renders JS and returns clean markdown. Many news sites and blogs work; some block it (403). Use it before falling back to screenshots.
3. **Use Camofox only when the above is insufficient.** Good for: JavaScript-heavy sites, pages that block jina.ai, consent popups, or when you need a screenshot for visual confirmation.
4. **Avoid Fandom, Reddit, and X for anonymous extraction.** All three actively block anonymous/automated access with Cloudflare, JS challenges, or login walls. Use them only as a last resort and expect failures.

### Content Extraction from SPAs (JS-heavy sites)

Many modern sites are React/SPA — `curl` gets empty `<div id="root">`. This includes Austrian government sites: **RIS** (Rechtsinformationssystem), **Findok** (BMF Steuerdokumente), WU Wien, ÖH WU. For legal research on RIS, see `references/ris-legal-research.md` for the proven workflow.

General extraction options for SPAs:

1. **links endpoint** (fast, no JS needed): `GET /tabs/:tabId/links?userId=kiwi` — returns link texts, but hrefs may be empty (JS-routed).
2. **screenshot + vision** (reliable): Take screenshot, `vision_analyze` it for visual content.
3. **jina.ai reader** (best for text extraction): `curl -sL "https://r.jina.ai/<URL>" -H "Accept: text/plain"` — renders JS and returns clean markdown. Use when browser-extracted content is insufficient.
4. **Hidden JSON APIs** (fastest, no browser needed): Many JS SPAs have backend API endpoints. Look for them in page source (`grep -oP 'api|endpoint|json|type=\d+'`), or try common patterns like `?type=INTEGER` on the page URL. Example: `ihr-notariat.at/notarfinder/?type=1602231006` returned the full Austrian notary database as JSON — avoiding the entire SPA. Always try this before launching browser automation for content extraction.
5. **evaluate endpoint**: `POST /tabs/:tabId/evaluate` — requires `CAMOFOX_API_KEY` unless loopback. For localhost calls without API key, prefer links + screenshot.

### Cookie / Consent Popups

Many EU sites (WU, ÖH, Herzstiftung, Deutsches Ärzteblatt) show cookie banners that overlay content and often resist automated dismissal. Dismiss via:
- `POST /tabs/:tabId/click` with selector `"button:has-text('Alle akzeptieren')"` or similar
- If clicking times out (popup blocks interaction), try waiting 2-3s first, then click
- Take screenshot after dismissal to verify
- For medical/government sites specifically, cookie walls and paywalls frequently defeat both `jina.ai` and Camofox `/click`. See `references/research-patterns.md` Pattern 5 for the full fallback chain.

### Prayer Times API

For Islamic prayer times, use the free Aladhan API. See `references/aladhan-prayer-times-api.md` for endpoints, parameters, and the high-latitude adjustment method needed for cities like Vienna.

### Islamic Fatwa & Religious Research

Fatwa sites (IslamQA.info, Islamweb.net) use **client-side JS routing** — URLs don't map to content. The `site:` search + screenshot + vision pattern is required to discover correct answer IDs. See `references/islamic-fatwa-research.md` for the full workflow, verified answer IDs, and the Wikipedia API approach for historical Muslim Freemasons.

### Gold & Precious Metals Valuation

For valuing gold coins, bars, and silver: combine live spot-price APIs (gold-api.com, exchangerate-api.com) with dealer-specific Camofox screenshots. See `references/gold-precious-metals-research.md` for the full two-layer workflow, Turkish coin reference table, and conversion formulas.

### Auth / sessionKey Convention

- **POST endpoints**: `userId` and `sessionKey` go in the **JSON body**, NOT as query params. Query params are ignored.
  ```bash
  # ✅ CORRECT
  curl -X POST "http://127.0.0.1:9377/tabs" \
    -d '{"userId":"kiwi","sessionKey":"default","url":"https://example.com"}'
  
  # ❌ WRONG — query params ignored
  curl -X POST "http://127.0.0.1:9377/tabs?userId=kiwi&sessionKey=default" \
    -d '{"url":"https://example.com"}'
  ```
- **GET endpoints** (screenshot, links): use **query params**.
  ```bash
  curl "http://127.0.0.1:9377/tabs/$TAB/screenshot?userId=kiwi&sessionKey=default"
  ```
- The `sessionKey` value is arbitrary — `"default"`, `"tuya"`, etc. all work as long as it's present.

### API Endpoint Quirks

| Endpoint | Method | Notes |
|----------|--------|-------|
| `/tabs` | POST | Create tab — `{userId, sessionKey, url}` in body → returns `tabId` |
| `/tabs?userId=kiwi` | GET | List all tabs for user — works |
| `/tabs/:tabId?userId=kiwi` | GET | May return 404 with current version — use listing instead |
| `/tabs/:tabId/links?userId=kiwi&sessionKey=X` | GET | Link extraction — JS-routed sites have empty hrefs (React SPA). Returns `{links, pagination}`. Buttons/submit inputs inside forms are NOT listed (they're not `<a>` tags) |
| `/tabs/:tabId/screenshot?userId=kiwi&sessionKey=X` | GET | Screenshot — works, reliable. Returns PNG via stdout |
| `/tabs/:tabId/evaluate` | POST | **BLOCKED without CAMOFOX_API_KEY** even on loopback. Returns `{"error":"This endpoint requires CAMOFOX_API_KEY except for loopback requests in non-production environments."}`. Workaround: use `/type` for form filling + `/click` for interaction |
| `/tabs/:tabId/type` | POST | Type text into an input field. Body: `{userId, sessionKey, selector, text}`. Returns `{"ok":true}`. Works for both text and password fields. Chain `/type` + `/click` as a substitute for `/evaluate` when API key is absent |
| `/tabs/:tabId/click` | POST | CSS selector click. Body: `{userId, sessionKey, selector}`. May return `{"error":"Internal server error"}` on submit buttons inside forms — `/type` + form interaction may be needed instead |
| `/tabs/:tabId/navigate` | POST | Set URL. Body: `{userId, sessionKey, url}`. **Cannot navigate to `javascript:` URLs** — returns "Bad Request". Only works with `http(s)://` URLs |
| `/health` | GET | Health check — `browserConnected` goes true lazily on first tab |

## Troubleshooting

- **Google returns 429/CAPTCHA during research:** Switch to DuckDuckGo or use r.jina.ai on the target URL directly. Do not keep retrying Google from the same IP.
- **Camofox nicht erreichbar:** `docker logs camofox-browser` prüfen.
- **403 bei gesetztem CAMOFOX_API_KEY:** Key entfernen, Sicherheit über Netzwerk-Binding sicherstellen.
- **Cookies/Logins nicht persistent:** Prüfen ob `/DATA/AppData/camofox` gemountet ist und `managed_persistence: true` in config.yaml steht.
- **noVNC nicht erreichbar:** Port 6080 nur an localhost gebunden? SSH-Tunnel nutzen: `ssh -L 6080:127.0.0.1:6080 user@zimaos`
- **`/root/.docker` read-only:** Auf ZimaOS `DOCKER_CONFIG=/tmp/docker-config` vor allen Docker-Befehlen setzen.
- **`make: command not found`:** ZimaOS hat kein make. Build-Schritte manuell ausführen (curl für Assets, docker build direkt).
- **`websockify: not found`:** Im Container `pip3 install --break-system-packages websockify` ausführen, dann `websockify --web /usr/share/novnc 0.0.0.0:6080 127.0.0.1:5900` starten.
- **`browserConnected: false` in Health:** Normal — Camoufox startet lazily erst beim ersten Tab-Request. Einen Tab öffnen, dann prüft Health auf `true`.
- **VNC-Plugin deaktiviert:** In `camofox.config.json` muss `"vnc": { "enabled": true, "resolution": "1920x1080" }` stehen. Per Volume-Mount überschreiben.