arise-browser 0.1.0

package/skill/arise-browser/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: arise-browser
+description: >
+  Control a headless or headed Chromium browser via AriseBrowser's HTTP API. Use for web automation,
+  scraping, form filling, navigation, and multi-tab workflows. AriseBrowser exposes a YAML accessibility
+  tree with persistent refs (WeakMap + aria-ref + signature), multi-strategy click fallbacks, and
+  behavior recording with Learn protocol export — built for AI agents that need reliable browser control.
+  Use when the task involves: browsing websites, filling forms, clicking buttons, extracting
+  page text, taking screenshots, recording workflows, or any browser-based automation.
+  Supports virtual display mode on Linux servers — runs a real headed Chrome with Xvfb + Neko WebRTC
+  streaming, allowing users to watch and interact with the AI-controlled browser in real time.
+homepage: https://github.com/AriseOS/arise-browser
+metadata:
+  openclaw:
+    emoji: "🚀"
+    requires:
+      bins: ["npx"]
+      env: |
+        ARISE_BROWSER_TOKEN (optional, secret) - Bearer auth token
+        ARISE_BROWSER_PORT (optional) - HTTP port, default 9867
+        ARISE_BROWSER_HEADLESS (optional) - true/false, default true
+        ARISE_BROWSER_PROFILE (optional) - Chromium profile directory
+        ARISE_BROWSER_BIND (optional) - Bind address, default 127.0.0.1
+        ARISE_BROWSER_VIRTUAL_DISPLAY (optional) - Enable headed mode with Xvfb + Neko (Linux only)
+        ARISE_BROWSER_NEKO_PORT (optional) - Neko WebRTC port, default 6090
+        ARISE_BROWSER_NEKO_PASSWORD (optional, secret) - Neko user password, default "neko"
+        ARISE_BROWSER_NEKO_ADMIN_PASSWORD (optional, secret) - Neko admin password, default "admin"
+---
+
+# AriseBrowser
+
+Industrial-grade browser automation for AI agents. Persistent refs, multi-strategy clicks, behavior recording.
+
+**Security Note:** AriseBrowser runs entirely locally. It does not contact external services or send telemetry. It controls a real Chromium instance — if pointed at a profile with saved logins, agents can access authenticated sites. Always use a dedicated empty profile and set ARISE_BROWSER_TOKEN when exposing the API. See [TRUST.md](TRUST.md) for the full security model.
+
+## Quick Start (Agent Workflow)
+
+```bash
+# 1. Start AriseBrowser (local on :9867)
+npx arise-browser &
+
+# 2. In your agent, follow this loop:
+#    a) Navigate to a URL
+#    b) Snapshot the page (get refs like e0, e5, e12)
+#    c) Act on a ref (click e5, type e12 "search text")
+#    d) Snapshot again to see the result
+#    e) Repeat until done
+```
+
+**Refs are persistent** — AriseBrowser's 3-layer ref system (WeakMap + aria-ref + signature) means refs survive across snapshots. You don't need to re-snapshot before every action.
+
+### Recommended Secure Setup
+
+```bash
+ARISE_BROWSER_BIND=127.0.0.1 \
+ARISE_BROWSER_TOKEN="your-strong-secret" \
+ARISE_BROWSER_PROFILE=~/.arise-browser/automation-profile \
+npx arise-browser &
+```
+
+**Never expose to 0.0.0.0 without a token. Never point at your daily browser profile.**
+
+## Setup
+
+### Headless Mode (default, any platform)
+
+```bash
+# Headless (default)
+npx arise-browser &
+
+# Headed — visible browser for debugging
+npx arise-browser --no-headless &
+
+# With auth token
+ARISE_BROWSER_TOKEN="your-secret-token" npx arise-browser &
+
+# Custom port
+npx arise-browser --port 8080 &
+
+# Connect to existing browser via CDP
+npx arise-browser --cdp http://localhost:9222 &
+
+# Persistent profile
+npx arise-browser --profile ~/.arise-browser/my-profile &
+```
+
+Default: **port 9867**, no auth required (local). Set `ARISE_BROWSER_TOKEN` for remote access.
+
+### Virtual Display Mode (Linux servers — headed + WebRTC streaming)
+
+Run a real headed Chrome on a headless Linux server. Users watch and interact via Neko WebRTC UI.
+
+```bash
+# 1. Install system dependencies (once, requires root)
+#    From npm package:
+sudo bash $(dirname $(which arise-browser))/../lib/node_modules/arise-browser/deploy/neko/setup.sh
+#    Or from git clone:
+#    sudo bash deploy/neko/setup.sh
+#    Or directly from GitHub:
+sudo bash <(curl -fsSL https://raw.githubusercontent.com/AriseOS/arise-browser/main/deploy/neko/setup.sh)
+
+# 2. Start with virtual display
+npx arise-browser --virtual-display --port 9867 --host 0.0.0.0 &
+
+# 3. AI agent uses the API as usual:
+curl -X POST http://localhost:9867/navigate -H 'Content-Type: application/json' -d '{"url":"https://example.com"}'
+
+# 4. Users open Neko in a browser to watch/interact:
+#    http://<server-ip>:6090  (password: neko)
+```
+
+Virtual display mode automatically:
+- Starts Xvfb (virtual X11 display)
+- Starts PulseAudio (virtual audio)
+- Starts Openbox (window manager, maximizes Chrome)
+- Launches Chrome with CDP on localhost:9222
+- Starts Neko server for WebRTC streaming
+- Connects arise-browser to Chrome via CDP
+
+All processes are managed as children of arise-browser — no supervisord needed.
+
+**Ports in virtual display mode:**
+
+| Port | Service | Access |
+|------|---------|--------|
+| 9867 | arise-browser API | AI agent |
+| 6090 | Neko WebRTC UI | User browser |
+| 52000-52100/udp | WebRTC data | User browser |
+| 9222 | Chrome CDP | localhost only |
+
+**Virtual display options:**
+
+```bash
+--virtual-display              # Enable virtual display mode
+--neko-port <port>             # Neko port (default: 6090)
+--neko-password <pwd>          # Neko user password (default: "neko")
+--neko-admin-password <pwd>    # Neko admin password (default: "admin")
+```
+
+## Core Workflow
+
+### 1. Navigate
+
+```bash
+curl -X POST http://localhost:9867/navigate \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com"}'
+```
+
+### 2. Snapshot
+
+```bash
+# YAML format (default, best for AI agents)
+curl http://localhost:9867/snapshot
+
+# JSON format (structured)
+curl "http://localhost:9867/snapshot?format=json"
+
+# Diff mode (only changes since last snapshot)
+curl "http://localhost:9867/snapshot?diff=true"
+```
+
+### 3. Act
+
+```bash
+# Click by ref
+curl -X POST http://localhost:9867/action \
+  -H "Content-Type: application/json" \
+  -d '{"kind": "click", "ref": "e5"}'
+
+# Type into field
+curl -X POST http://localhost:9867/action \
+  -H "Content-Type: application/json" \
+  -d '{"kind": "type", "ref": "e12", "text": "hello world"}'
+
+# Press key
+curl -X POST http://localhost:9867/action \
+  -H "Content-Type: application/json" \
+  -d '{"kind": "press", "key": "Enter"}'
+
+# Scroll down
+curl -X POST http://localhost:9867/action \
+  -H "Content-Type: application/json" \
+  -d '{"kind": "scroll", "scrollY": 300}'
+
+# Hover
+curl -X POST http://localhost:9867/action \
+  -H "Content-Type: application/json" \
+  -d '{"kind": "hover", "ref": "e7"}'
+
+# Select option
+curl -X POST http://localhost:9867/action \
+  -H "Content-Type: application/json" \
+  -d '{"kind": "select", "ref": "e3", "value": "option1"}'
+```
+
+### 4. Record & Export
+
+```bash
+# Start recording
+curl -X POST http://localhost:9867/recording/start
+# => {"recordingId": "session_20260303T180000"}
+
+# ... perform actions ...
+
+# Stop recording
+curl -X POST http://localhost:9867/recording/stop \
+  -d '{"recordingId": "session_20260303T180000"}'
+
+# Export as Learn protocol
+curl -X POST http://localhost:9867/recording/export \
+  -d '{"recordingId": "session_20260303T180000", "task": "Search for AI products"}'
+```
+
+Stopped recordings remain exportable for a limited retention window, so `stop -> export` is a supported flow.
+
+## API Reference
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check |
+| `/tabs` | GET | List all tabs |
+| `/navigate` | POST | Navigate to URL |
+| `/snapshot` | GET | Accessibility tree snapshot |
+| `/action` | POST | Execute single action |
+| `/actions` | POST | Execute batch actions |
+| `/text` | GET | Extract page text |
+| `/screenshot` | GET | JPEG screenshot |
+| `/pdf` | GET | PDF export |
+| `/evaluate` | POST | Execute JavaScript |
+| `/tab` | POST | Create/close/switch tabs |
+| `/tab/lock` | POST | Lock tab (multi-agent) |
+| `/tab/unlock` | POST | Unlock tab |
+| `/cookies` | GET/POST | Read/write cookies |
+| `/recording/start` | POST | Start recording |
+| `/recording/stop` | POST | Stop recording |
+| `/recording/status` | GET | Recording status |
+| `/recording/export` | POST | Export Learn format |
+
+Notes:
+- Read routes support optional `tabId` where applicable.
+- Write routes targeting a locked tab accept optional `owner`; mismatches return `423 Locked`.
+- `/navigate` accepts optional `tabId` and `timeout` (milliseconds).
+
+## Why AriseBrowser over Pinchtab?
+
+| Feature | AriseBrowser | Pinchtab |
+|---------|----------|----------|
+| Persistent Refs | 3-layer (WeakMap + aria-ref + signature) | Single pass |
+| Click Strategy | Ctrl+Click → Force Click fallback | Single attempt |
+| Select support | Full implementation | Empty stub |
+| Behavior Recording | Built-in + Learn protocol export | Not available |
+| Coordinate handling | Viewport-validated | Hardcoded (0,0) |
+| Virtual Display | Xvfb + Neko WebRTC (headed on servers) | Not available |
+| Runtime | Node.js + Playwright | Go + CDP |
+
+## Token Cost Guide
+
+- Snapshot (YAML): ~500-2000 tokens depending on page complexity
+- Snapshot (JSON): ~300-1500 tokens
+- Action response: ~50-100 tokens
+- Recording export: ~100-500 tokens per workflow
+
+## Pinchtab Compatibility
+
+AriseBrowser accepts Pinchtab's `kind` field in `/action`:
+- `kind: "click"` → click
+- `kind: "type"` / `kind: "fill"` → type
+- `kind: "press"` → press_key
+- `kind: "scroll"` (with `scrollY`) → scroll
+- `kind: "hover"` → hover
+- `kind: "select"` → select
+- `kind: "focus"` → focus
+
+Environment variables `BRIDGE_*` are also accepted as aliases for `ARISE_BROWSER_*`.

package/skill/arise-browser/TRUST.md

@@ -0,0 +1,42 @@
+# AriseBrowser Trust & Security Model
+
+## What AriseBrowser Does
+
+AriseBrowser is a local HTTP server that controls a Chromium browser via Playwright. It:
+- Listens on localhost only (127.0.0.1) by default
+- Does NOT contact external services
+- Does NOT send telemetry or analytics
+- Does NOT store data beyond the current session
+
+## Security Boundaries
+
+### Network
+- Binds to 127.0.0.1 by default (local only)
+- Optional Bearer token authentication (`ARISE_BROWSER_TOKEN`)
+- No TLS built-in (use reverse proxy for remote access)
+
+### Browser
+- Uses Playwright's Chromium (not your system Chrome)
+- Default: fresh profile with no saved data
+- `--profile` mode: accesses saved logins, cookies, history
+- Stealth headers enabled by default to avoid bot detection
+
+### Data
+- Snapshots and actions are ephemeral (not persisted)
+- Recordings are in-memory only, cleared on server restart
+- No data is written to disk unless `--profile` is used
+
+## Recommendations
+
+1. **Always set `ARISE_BROWSER_TOKEN`** when the API is accessible to other processes
+2. **Never use `--profile` with your daily browser profile** — create a dedicated one
+3. **Never bind to 0.0.0.0** without token authentication
+4. **Review `/evaluate` usage** — it executes arbitrary JavaScript in the page context
+
+## Dependencies
+
+- `playwright` — Browser automation (Microsoft, Apache-2.0)
+- `fastify` — HTTP framework (MIT)
+- `pino` — Logging (MIT)
+
+All dependencies are widely used, well-maintained, and open source.

package/skill/arise-browser/references/api.md

@@ -0,0 +1,198 @@
+# AriseBrowser API Reference
+
+Base URL: `http://localhost:9867`
+
+## Health
+
+### GET /health
+Returns server status.
+
+Response:
+```json
+{"status": "ok", "connected": true, "version": "0.1.0"}
+```
+
+## Navigation
+
+### POST /navigate
+Navigate to a URL.
+
+Body:
+```json
+{"url": "https://example.com", "newTab": false, "tabId": "tab-001", "timeout": 15000}
+```
+
+Response:
+```json
+{"message": "Navigated to https://example.com", "url": "https://example.com"}
+```
+
+## Snapshot
+
+### GET /snapshot
+Get accessibility tree snapshot.
+
+Query params:
+- `tabId`: snapshot a specific tab without switching the global current tab
+- `format`: `yaml` (default), `json`, `compact`, `text`
+- `diff`: `true`/`false` — return only changes since last snapshot
+- `viewportLimit`: `true`/`false` — limit to visible viewport
+
+Response (yaml):
+```json
+{"snapshot": "- Page Snapshot\n```yaml\n...\n```", "format": "yaml"}
+```
+
+Response (json):
+```json
+{"nodes": [{"ref": "e0", "role": "link", "name": "Home"}], "url": "...", "title": "...", "count": 42}
+```
+
+## Actions
+
+### POST /action
+Execute a single browser action.
+
+Body (AriseBrowser native):
+```json
+{"type": "click", "ref": "e5", "tabId": "tab-001", "owner": "agent-1"}
+```
+
+Body (Pinchtab-compatible):
+```json
+{"kind": "click", "ref": "e5"}
+```
+
+Supported kinds: `click`, `type`, `fill`, `press`, `hover`, `scroll`, `select`, `focus`
+
+### POST /actions
+Execute multiple actions sequentially.
+
+Body:
+```json
+{"actions": [{"type": "click", "ref": "e5", "tabId": "tab-001"}], "owner": "agent-1", "stopOnError": true}
+```
+
+## Content
+
+### GET /text
+Extract page text content.
+Query params: `tabId` (optional)
+
+### GET /screenshot
+Get JPEG screenshot.
+
+Query params:
+- `tabId`: specific tab (optional)
+- `quality`: 1-100 (default 75)
+- `raw`: `true` returns raw JPEG bytes
+
+### GET /pdf
+Export page as PDF.
+Query params: `tabId` (optional)
+
+### POST /evaluate
+Execute JavaScript in page context.
+
+Body:
+```json
+{"expression": "document.title", "tabId": "tab-001", "owner": "agent-1"}
+```
+
+## Tabs
+
+### GET /tabs
+List all open tabs.
+
+### POST /tab
+Create, close, or switch tabs.
+
+Body:
+```json
+{"action": "create", "url": "https://example.com"}
+{"action": "close", "tabId": "tab-001"}
+{"action": "switch", "tabId": "tab-002"}
+```
+
+### POST /tab/lock
+Lock a tab for exclusive use.
+Locked write routes return `423 Locked` unless the same `owner` is supplied.
+
+Body:
+```json
+{"tabId": "tab-001", "owner": "agent-1", "ttlMs": 60000}
+```
+
+### POST /tab/unlock
+Release a tab lock.
+
+Body:
+```json
+{"tabId": "tab-001", "owner": "agent-1"}
+```
+
+## Cookies
+
+### GET /cookies
+Get all cookies.
+
+### POST /cookies
+Set cookies.
+
+Body:
+```json
+{"cookies": [{"name": "session", "value": "abc123", "url": "https://example.com"}]}
+```
+
+## Recording
+
+### POST /recording/start
+Start behavior recording.
+
+Response:
+```json
+{"recordingId": "session_20260303T180000"}
+```
+
+### POST /recording/stop
+Stop recording and get operations.
+
+Body:
+```json
+{"recordingId": "session_20260303T180000"}
+```
+
+### GET /recording/status
+Check recording status.
+
+Query params:
+- `recordingId`: specific recording (optional)
+
+### POST /recording/export
+Export recording as Learn protocol format.
+Works for active recordings and recently stopped recordings retained in memory.
+
+Body:
+```json
+{"recordingId": "session_20260303T180000", "task": "Search for AI products"}
+```
+
+Response:
+```json
+{
+  "type": "browser_workflow",
+  "task": "Search for AI products",
+  "success": true,
+  "domain": "producthunt.com",
+  "steps": [
+    {"url": "https://producthunt.com", "action": "navigate"},
+    {"url": "https://producthunt.com", "action": "click", "target": "Search"},
+    {"url": "https://producthunt.com", "action": "type", "target": "e12", "value": "AI"}
+  ],
+  "metadata": {
+    "duration_ms": 15000,
+    "page_count": 3,
+    "recorded_at": "2026-03-03T18:00:00Z"
+  }
+}
+```