WebRobo API

Browser automation API with built-in anti-bot stealth. Send a URL and a sequence of declarative actions — fill a field, click, wait for an element — and get back the rendered page, including sites behind Cloudflare-style JS challenges.

Status

Early MVP (v0), under active development. Single browser engine, no queue, no billing yet — see Roadmap.

Architecture

Client → Caddy (TLS) → FastAPI → API-key auth → semaphore acquire
                                                       │
                                                       ▼
                                          Camoufox browser context
                                          (run actions, collect result)
                                                       │
                                                       ▼
                                          release semaphore → response

• Engine: Camoufox (stealth Firefox, driven via Playwright). Chosen for v1 because Firefox-based fingerprinting is less commoditized against anti-bot vendors than patched Chromium.
• API: FastAPI, single versioned endpoint (POST /v1/solve).
• Concurrency: bounded by an asyncio.Semaphore over browser contexts — no external job queue in v1. Simpler to run, hard ceiling on throughput per instance (see Roadmap for scaling out).
• Auth: per-client API key (X-API-Key header), checked against a SQLite table. (SQLAlchemy ORM)
• Logging: every request's outcome (success/failure/duration) is persisted — this becomes the success-rate data used to evaluate the service and talk to clients about reliability.
• Proxies: not managed by the service in v1 — the client supplies their own proxy per request if they need one.
• Deployment: single Docker container behind a Caddy reverse proxy.
• Canvas fingerprint по дизайну генерируется каждую сессию новый.

Planned project layout

src/
  main.py            # FastAPI app + router wiring
  config.py          # settings (env vars)
  api/
    solve.py         # POST /v1/solve
    deps.py          # API-key auth dependency
  engine/
    browser.py       # Camoufox context pool + semaphore
    actions.py       # fill / click / wait_for execution
    schemas.py       # SolveRequest / SolveResponse / Action models
  db/
    models.py        # api_keys, request_logs
    session.py
tests/
wheels/              # whl библиотеки для оффлайн установки под Ubuntu Noble
Dockerfile
requirements.txt
env.example

API (draft)

POST /v1/solve
X-API-Key: <key>

{
	"captcha": "token",
	"url": "https://example.com/login",
	"actions": [
		{"type": "fill", "selector": "#email",  "value": "user@example.com"},
		{"type": "fill", "selector": "#password", "value": "..."},
		{"type": "mouse_move", "selector": "#submit"},
		{"type": "click", "selector": "#submit"},
		{"type": "wait_for", "selector": ".dashboard", "timeout": 30}
	],
	"proxy": "socks5://user:pass@host:port",
	
	"screen": "1280x920",
	"user_agent": "Firefox",
	"timeout": 120
}

Response:

{
	"ok": false,
	"context": "000000",
	"error": "action_error",
	"html": "<html>...</html>",
	"cookies": [
		{
			"name": "session",
			"value": "..."
		}
	],
	"actions_result": [
		{
			"type": "fill",
			"ok": true
		},
		{
			"type": "fill",
			"ok": true
		},
		{
			"type": "click",
			"ok": true
		},
		{
			"type": "wait_for",
			"ok": false,
			"error": "Element not located"
		}
	]
}

On failure, status is "error" and error carries a machine-readable reason (selector_not_found, timeout, navigation_failed, ...).

Fill команда включает 3 действия

1. {"type": "mouse_move", "selector": "#email"}, - навести мышку на элемент
2. {"type": "click"}, - клик в текущие координаты
3. {"type": "typing", "value": "user@example.com"}, - набор текста

Roadmap

Deliberately out of scope for v1:

• Job queue (Redis/RabbitMQ) + multiple worker VPS for horizontal scaling
• Real billing/usage plans beyond a flat API-key check
• Broader action vocabulary beyond fill/click/wait_for
• Second engine (Patchright/Chromium) for targets where the Firefox fingerprint doesn't fit

Local development

python -m venv .venv
source .venv/bin/activate
make sync-offline
uvicorn app.main:app --reload

TODO:

-[ ] добавить пакет обертку для python -[ ]