ViperCapture

Self-hosted browser rendering API.

ViperCapture is an MIT-licensed browser renderer for your own infrastructure. Send a URL, HTML, or Markdown to produce screenshots, PDFs, AVIF images, WebM/MP4/GIF video, hydrated HTML, Markdown, or structured metadata through a JSON API.

Important

ViperCapture OSS v0.3 is beta software. You can self-host and evaluate the engine and API, but the public API may change before v1.

The API does not implement every option from other rendering services. Check the dated compatibility matrix and run the benchmark with your own workload before migrating.

Features

• Chromium, Firefox, and WebKit rendering; browsers start only when needed
• PNG, JPEG, WebP, AVIF, PDF, HTML, Markdown, metadata, and WebM/MP4/GIF output
• URL, raw HTML, and Markdown input; full-page, viewport, element, clip, and multi-viewport ZIP captures
• Typed click, hover, fill, select, key, scroll, wait, hide, and opt-in JavaScript actions
• Wait conditions, assertions, custom CSS, devices, locale/timezone, geolocation, cookies, user agent, proxy, resource blocking, and cleanup
• Request-aware stealth controls, operator-controlled residential/datacenter proxies, and structured detection for common CAPTCHA and bot interstitials
• Ad, tracker, chat, newsletter, and consent-banner cleanup backed by the vendored, license-preserved AutoConsent rule set
• Cleanup and deterministic controls in the browser UI
• Timed, full-page GIF, WebM, and MP4 capture with higher-quality encoding, transparent padding where supported, and optional GPU acceleration with a safe software fallback
• Default local limits: 500 megapixels, 16,384-pixel viewports, and 100,000-pixel full-page height, all configurable for remote hosting
• Durable encrypted async jobs, idempotency, retries, polling, cancellation, bulk submission, cron schedules, and signed webhook callbacks
• Private local result storage or built-in S3-compatible storage for AWS S3, Cloudflare R2, MinIO, Backblaze B2, and compatible providers
• Expiring HMAC-signed render URLs and a 15-minute exact-request image cache
• Visual regression ZIPs with pixel counts, pass/fail thresholds, bounds, and highlighted changes
• Diagnostic ZIPs with console/network data and optional HAR, redacted Playwright trace, and WARC; Ed25519-certified artifact bundles
• Deterministic capture controls, sectioned slice ZIPs, project-owned visual baselines, and reproducible comparison reports
• Optional projects, hashed API keys, quotas, resource ownership, encrypted persistent profiles, portable browser-session imports, audit logs, Prometheus metrics, and OTLP tracing
• Separate API/worker roles for horizontally scaled provider-backed queues, plus ScreenshotOne and Urlbox compatibility adapters
• Bounded concurrency, output/pixel/deadline limits, client-disconnect cancellation, consistent error envelopes, and hosted-mode SSRF defenses
• Browser UI, Docker Compose, SDKs, integrations, and a portable agent skill
• Reproducible workflows for sustained load, forced restart recovery, constrained memory, same-host competitor tests, and longer real-site runs

Before you begin

Direct installation requires Python 3.11 or newer and a full FFmpeg build on PATH. Video output needs the libvpx, libvpx-vp9, and libx264 encoders; GPU video also needs the matching hardware encoder and driver. Use your OS package manager or the FFmpeg download page. Run ffmpeg -encoders to confirm the encoders are available. The Docker image already includes FFmpeg.

Install locally

Run:

git clone https://github.com/Viperisuseful/ViperCapture.git
cd ViperCapture
python launch.py

The launcher creates a virtual environment, installs Chromium, Firefox, and WebKit, starts the API, and opens http://127.0.0.1:8000.

To use Docker instead, run:

docker compose up --build

By default, Compose binds only to loopback. It keeps durable queue state, encryption keys, schedules, cache entries, and local artifacts in a named volume. Read self-hosting before exposing the service to a network. Set separate VIPERCAPTURE_ADMIN_TOKEN and VIPERCAPTURE_CONTROL_SECRET values to enable the built-in project control plane before exposing API routes to multiple tenants.

Send a render request

curl --fail-with-body http://127.0.0.1:8000/v1/render \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "output": "png",
    "full_page": false,
    "viewport": {"width": 1280, "height": 720},
    "actions": [{"type": "hide", "selector": ".newsletter"}],
    "cleanup": {"block_ads": true, "consent_mode": "reject"},
    "assertions": {"content_includes": ["Example Domain"]}
  }' --output example.png

A synchronous request returns the artifact directly. The X-ViperCapture-* headers include the request ID, queue and render timing, dimensions, navigation status, and cache outcome.

For work that must survive a dropped connection, send the same render object to POST /v1/jobs. Poll GET /v1/jobs/{id}, download GET /v1/jobs/{id}/result, or receive a signed callback by setting delivery.webhook_url. Related orchestration endpoints:

Endpoint	Purpose
POST /v1/jobs/bulk	Best-effort submission of up to 100 independently idempotent jobs
POST/GET/PATCH/DELETE /v1/schedules	Encrypted five-field cron schedules with IANA time zones
POST /v1/signed-url	Mint an expiring HMAC render link
GET /v1/render/signed	Render through a verified signed link
POST /v1/diff	Compare two images and download a deterministic report ZIP
PUT/GET/POST /v1/baselines	Store project baselines and compare review bundles
POST/DELETE /v1/profiles	Manage encrypted Playwright storage-state profiles
POST /v1/profiles/import	Import pasted Cookie headers or browser-exported session files
GET /take	ScreenshotOne-compatible common-options adapter
POST /compat/urlbox/v1/render/{sync,async}	Urlbox-compatible adapters

See the API and workflows guide, async provider guide, platform/operator guide, public API deployment, stable-v1 gates, release guide, and migration guide. If a site you administer challenges the renderer, follow the least-privilege Cloudflare/WAF authorization guide.

Use proxies, sessions, and CAPTCHA hooks

Self-hosted renders can route an isolated browser context through an HTTP, HTTPS, SOCKS4, or SOCKS5 proxy. Keep credentials in separate fields instead of embedding them in the proxy URL:

{
  "url": "https://example.com",
  "network": {
    "proxy": {
      "server": "socks5://proxy.example:1080",
      "username": "account-zone-residential",
      "password": "secret"
    }
  }
}

With the project control plane enabled, POST /v1/profiles/import normalizes Playwright storage state, Cookie-Editor JSON, Netscape cookies.txt, or a pasted Cookie header into an encrypted profile. Pass its returned id as profile_id on later renders. Imports preserve local storage and partitioned cookies where the export format supports them.

ViperCapture detects common blocking CAPTCHA and bot interstitials but does not solve or bypass them. The default captcha.action is error; use capture to render the challenge as-is. Operators may configure their own approved async handler with VIPERCAPTURE_CAPTCHA_HANDLER_FACTORY and opt in per request with captcha.action: "external". See the API guide for the handler contract and timeout behavior.

Configure storage and webhooks

Set VIPERCAPTURE_S3_BUCKET to store job results through the built-in S3 adapter instead of local files. It uses standard AWS credential resolution. R2 and MinIO also need an endpoint URL and, where appropriate, path-style addressing. The docker-compose.s3.yml overlay provides a complete local MinIO example:

export MINIO_ROOT_PASSWORD='replace-with-at-least-a-long-random-secret'
docker compose -f docker-compose.yml -f docker-compose.s3.yml up --build

Set VIPERCAPTURE_WEBHOOK_SECRET to enable callbacks. Each callback contains canonical JSON signed with HMAC-SHA256 in X-ViperCapture-Webhook-Signature. Timestamp and event-ID headers support verification and deduplication. Private callback targets are rejected unless the operator explicitly opts in. Public DNS results stay pinned for the life of the callback connection to prevent rebinding, and the encrypted delivery outbox survives process restarts.

Secure the service

Keep the service on loopback, enable VIPERCAPTURE_ADMIN_TOKEN, or put every route behind the same authenticated, rate-limited reverse proxy. When the control plane is disabled, job and schedule UUIDs identify resources but do not provide access control. Hosted mode rejects targets and redirects that resolve to private addresses during validation, along with unsafe subresources, cross-origin credential headers, proxy use, and cross-site cookies. Browser DNS can change after validation, so deployments also need host or container egress rules to block rebinding. Self-host mode allows internal pages and proxies; isolate Chromium with that boundary in mind.

JavaScript actions are disabled unless VIPERCAPTURE_ALLOW_SCRIPTS=1. Render inputs can contain credentials and private page data. Async and scheduled inputs are AES-GCM encrypted and erased at terminal job states, but diagnostic console output and browser video can still record sensitive page content. Treat those artifacts accordingly.

Use the agent skill

The portable skills/vipercapture skill works with Codex, Claude Code, and Cursor and includes a dependency-free client.

Run development checks

python -m pip install -r requirements.txt
python -m playwright install chromium firefox webkit
python -m unittest -v
npm ci --prefix frontend && npm run lint --prefix frontend && npm run build --prefix frontend

CI runs the renderer suite and builds the web interface. Benchmarks write the raw samples used in their reports and do not fill in missing competitor data. Use your own provider credentials to compare services from the same host with the same scenario file.

License

MIT. AutoConsent assets under vendor/autoconsent retain their upstream license and attribution.