Surf Cloud v2
From Wave Wiki — the open reference for the Wave OS ecosystem.
1. About
Surf Cloud v2 is Wave OS's AI-powered cloud browser, running a headless Chromium instance with Playwright on a Railway container. It provides per-user isolated browser sessions with AI element resolution powered by Theta EdgeCloud GLM-5.2. Users can navigate, observe, extract data, perform AI-driven actions, record sessions, and take screenshots — all through a simple REST API. The noVNC viewer provides a live visual of the browser for real-time observation.
Surf's AI features — the Ask AI panel, element resolution, and page data extraction — now route through Wave Assistant's private dedicated endpoint on Theta EdgeCloud (GLM-5.2), rather than the shared public gateway. This makes Surf's AI features resilient to shared-gateway outages.
2. Tech Stack
Backend: Python FastAPI (api_v2.py) on Railway. Browser Engine: Chromium + Playwright with CDP. AI Resolution: Theta EdgeCloud GLM-5.2 for observe/act/extract. Session Isolation: per-user BrowserContext instances (max 50 concurrent). Visual: noVNC (websockify) with Wave OS dark theme branding. Reverse Proxy: Nginx. Container: Debian bookworm-slim, Docker. GitHub: xBuildy/surf-cloud. URL: https://surf-cloud-production.up.railway.app. API Key: surf-default-key (sent in the JSON body, not a header).
3. Install
No installation required. Surf Cloud is a server-side service accessed via REST API from the Wave OS Surf app. The noVNC viewer is embedded as an iframe at /novnc/vnc.html. The backend function surfAutomateV2.ts handles the API calls from the Wave OS frontend.
3a. Key API Endpoints
Resilience: if the private Theta AI endpoint is temporarily rate-limited or unavailable, Surf automatically retries briefly, then degrades gracefully — element clicks and actions fall back to smart heuristic matching, and data extraction returns a clear "AI temporarily unavailable, try again shortly" signal instead of failing the whole action. Deterministic browser actions (navigate, click, type, screenshot) are unaffected either way.
All endpoints are POST with a JSON body: /api/session/create — create isolated browser session {user_id, api_key}. /api/navigate — navigate to URL {url, user_id, api_key}. /api/observe — AI element resolution {instruction, user_id, api_key}. /api/act — AI-driven action {instruction, user_id, api_key}. /api/extract — AI data extraction {instruction, user_id, api_key}. /api/screenshot — capture screenshot {user_id, api_key}. /api/content — get page text content {user_id, api_key}. /api/fill — fill form fields {selector, value, user_id, api_key}. /api/click — click element {selector, user_id, api_key}. /api/type — type text {selector, text, user_id, api_key}. /api/record/start — start recording {user_id, api_key}. /api/record/stop — stop recording {user_id, api_key}. /api/session/close — close session {user_id, api_key}.
4. Pricing & Credits
Surf Cloud runs on Railway infrastructure. No per-user cost — the container is always-on. AI automation requests (observe/act/extract) consume Theta EdgeCloud compute credits via GLM-5.2 inference. Standard Wave OS credit rates apply for AI operations.
5. Known Limitations
Maximum 50 concurrent browser sessions. 30-minute idle timeout per session. Theta API must be configured for AI endpoints (observe/act/extract) — returns an error if THETA_API_KEY is missing. noVNC viewer requires WebSocket support. Sessions are ephemeral — no persistent state across container restarts. Recording requires manual start/stop. Heavy-volume AI-assisted automation (many rapid Ask-AI/extract calls in a short window) may occasionally hit a brief rate-limit pause on the dedicated endpoint; retries are automatic.
6. Privacy & Data
Each user gets an isolated Playwright BrowserContext — no cross-user data leakage. Sessions are ephemeral and cleared on close or timeout. No browsing history or session data is persisted to disk. API calls are authenticated via API key in the request body. All AI processing happens on Theta EdgeCloud, not on Base44.
7. Published
Published August 13, 2026.