Vitna Unblocker
Hosted alpha. Vitna Unblocker is a browser-backed web access API: send a public HTTPS URL and receive the rendered HTML, the readable text and the links, or a validated JSON feed, with a receipt of every attempt. It is hosted at https://unblock.vitna.ai, takes an alpha key issued on request, and is relayed at https://vitna.ai/api/v1/unblock. Billing is not active.
The product page is vitna.ai/unblocker. An alpha key starts vitna_unblock_ and is issued once a person has checked the fit of one workload: request it at vitna.ai/unblocker#alpha-access. An org's platform key (vitna_key_) works too, at the hosted endpoint and through the relay; see One key for the hosted APIs. The prices on the product page are proposed and nothing can be bought yet. The console's Plan page counts each org's delivered pages per UTC month, from the receipts of requests made with its platform key, in the unit those prices name. Managed proxy capacity and image CAPTCHA solving are not offered.
Hosted access
Send each request to the hosted endpoint with the key as a bearer token:
curl https://unblock.vitna.ai/v1/unblock \
-H "Authorization: Bearer $VITNA_UNBLOCKER_KEY" \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com/","render":true,"output":"json","timeoutMs":30000}'The website relays the same request, with the same key, at https://vitna.ai/api/v1/unblock. The relay forwards the key unchanged, refuses a body over 8 KiB, and does no browser work itself; the product page's live playground sends through it.
Signed in to the console, vitna.ai/console/unblocker runs the same request with the org's platform key: it checks each field against the service's own rules before sending, shows the page and every attempt it took, prints the request as curl, JavaScript and Python, and links the run to its record in Activity.
Authenticated GET /v1/status reports the limits that apply to your key, what it has used of them, and that billing is not enabled. It renders nothing and consumes no allowance:
curl https://unblock.vitna.ai/v1/status \
-H "Authorization: Bearer $VITNA_UNBLOCKER_KEY"Each key has a per-minute and a daily allowance, counted across the hosted service's processes. A request past either is refused with 429 and rate_limited or daily_limit, and a Retry-After header gives the seconds until the allowance resets. Refused pages count against the allowance as delivered ones do. When every browser slot is in use the answer is 429 with service_busy, also with Retry-After. The hosted service runs the native browser profile; see Browser profiles and live checks.
Keep the key on your server, never in a page a browser loads or in a repository. The service stores only its SHA-256 hash, so a lost key cannot be read back: ask for a new one through the contact form at vitna.ai/start#contact, which is also where to ask for help.
Request
The service serves this endpoint, hosted at https://unblock.vitna.ai:
POST /v1/unblockThe website relays to it. It forwards the caller's key; it has no shared service key and performs no browser work itself:
POST /api/v1/unblockThe relay is an operator setting, VITNA_UNBLOCKER_SERVICE_URL; without it the website endpoint returns 503 with service_not_configured. The product playground defaults to an explicitly illustrative example; its Live API mode uses this relay.
curl https://unblock.vitna.ai/v1/unblock \
-H "Authorization: Bearer $VITNA_UNBLOCKER_KEY" \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com/","render":true,"output":"json","timeoutMs":30000}'| Field | Default | Meaning |
|---|---|---|
url | Required | Public HTTPS URL, at most 4,096 characters; query strings are supported |
render | true | Execute JavaScript; false opens the page with JavaScript disabled |
output | json | json returns HTML, text, and links; html or text returns that string |
waitFor | Omitted | CSS selector to wait for until visible; requires JavaScript rendering |
timeoutMs | 30,000 | Total deadline across attempts, capped by the deployment; 1,000 to 60,000 |
retries | 1 | Additional attempts, from 0 to 2 |
country | Omitted | Two uppercase letters selecting a configured proxy route that serves that country |
network | auto | auto starts on the cheapest configured route and steps up a tier after a block; datacenter, isp, or residential uses only routes of that kind |
session | Omitted | 1 to 64 letters, numbers, underscores, or hyphens; sticky proxy selection and identifier for optional persistence |
persistSession | false | Boolean; restores and saves cookies and localStorage for the authenticated client and session; requires a session identifier |
actions | Omitted | Up to 50 ordered scroll, wait, click, write or press objects; requires render: true; uses the bounds below |
language | Browser default | BCP 47 locale, at most 35 characters, such as en-US |
viewport | Desktop default | { "width": 1440, "height": 960 }; width 320 to 4,096, height 240 to 4,096 |
headers | Omitted | Only accept-language up to 200 ASCII characters and dnt equal to 0 or 1 |
Without a selector, rendering waits for meaningful visible content after DOM readiness and any recognized browser verification. The browser allows an initial 500-millisecond grace period, then requires 200 milliseconds of stable content, within five seconds or the remaining request deadline. A page that still presents an empty or loading state returns target_incomplete, which can be retried within the request budget. Set waitFor for pages whose useful content appears later. A waitFor selector that never becomes visible fails with selector_timeout before the deadline: the wait stops up to 1.5 seconds short (a quarter of what remains, on a short budget) so the response names the selector rather than target_timeout. A retry waits within what is left of timeoutMs, not a fresh budget. HTML is the browser's serialized DOM, including content added by scripts, rather than the original response bytes. Text extraction prefers main/article content and removes scripts, navigation, and hidden attributes. It does not infer a schema or run an LLM. Links are resolved public HTTPS URLs. meta.delivered confirms an accepted readable snapshot. It does not establish that every application-specific data field or delayed item is ready.
Published text inside ASP.NET form wrappers is retained. Text in input controls, navigation, and hidden attributes remains excluded. A secondary loading widget does not prevent delivery when the page already contains substantial published content; an empty or loading-only content region still fails readiness. Automatic readiness also waits for in-flight, same-origin Q4 GET feeds matching /feed/*.svc/Get* before starting the stable-content interval. This remains within the existing five-second readiness deadline and does not wait for general network idleness. Use waitFor for slower archives or application-specific completion.
For application/json and application/*+json destinations, output: "json" returns { "html": "", "text": "original response body", "links": [], "data": ... }. The envelope's contentType identifies the destination MIME type. output: "text" returns the JSON text. This reads and validates the decoded navigation response, not Chromium's JSON viewer DOM. Malformed JSON returns target_invalid_json; the same two-MiB body limit, HTTP status, challenge, network, and deadline checks apply. An unsuccessful status is judged before the body is parsed, so an error body that is empty or not JSON still returns target_blocked or target_http_error. A body nested more than 512 levels deep is delivered as text without data. HTML output, selectors, actions, and captures are unsupported for JSON feeds.
An operator integrating createBrowserRenderer can set blockedResourceHosts to at most 50 lowercase DNS hostnames. Exact hosts and their subdomains are excluded before optional resources consume the 400-request budget. This is an internal factory option, unavailable in public API requests, and defaults to an empty list. Main navigations and recognized verification resources remain allowed. For IR collection, operators can use observed chart and analytics hosts to avoid spending the page budget on unrelated widgets; required issuer scripts and feed hosts must remain available. The standalone service reads the JSON array from VITNA_UNBLOCKER_BLOCKED_RESOURCE_HOSTS, defaulting to []. For example, ["tradingview-widget.com", "s.tradingview.com", "s3.tradingview.com"] excludes the optional chart embeds observed on GROW's IR page. Do not apply that profile to work that requires those charts.
To reduce unnecessary waiting, set waitFor to a selector that identifies the content you need. This replaces the automatic content-readiness wait and returns as soon as that content is visible after verification. Choose populated content rather than a container that also exists during loading. For the public ScrapingCourse challenge demos, the verified heading is #challenge-title:
{
"url": "https://www.scrapingcourse.com/cloudflare-challenge",
"render": true,
"output": "text",
"waitFor": "#challenge-title"
}The selector controls when the snapshot is taken. It does not shorten a destination's verification or deliberate JavaScript delay.
Browser actions
Actions run in order after navigation and recognized verification, before waitFor or the automatic content-readiness check. They dismiss a consent banner, press a "load more" button, open collapsed answers, type into a search box, and scroll a feed, so the snapshot holds what those steps reveal. A sequence holds at most 50 actions and shares the request's deadline, less a short reserve for the read that follows it.
| Action | Fields | Bounds |
|---|---|---|
| Scroll by pixels | { "type": "scroll", "y": 2000, "x": 0 } | Integer y from -20,000 to 20,000; optional integer x from -4,096 to 4,096, default 0 |
| Scroll a screen | { "type": "scroll", "direction": "down" } | up or down by one viewport; with selector, scrolls that element by its own height, for a feed in a scrollable box |
| Fixed wait | { "type": "wait", "milliseconds": 250 } | Integer milliseconds from 1 to 10,000; total fixed waits at most 30,000 milliseconds |
| Selector wait | { "type": "wait", "selector": "#loaded" } | Waits until the element is visible, for at most 10 seconds |
| Click | { "type": "click", "selector": "#accept" } | Waits up to 10 seconds for the first match to be visible and able to receive the click; "all": true clicks every match, up to 20 |
| Write | { "type": "write", "text": "Q3 2026", "selector": "#q" } | Types 1 to 1,000 characters; with selector it clicks that field first, otherwise it types into the focused element; a tab or line break types as Tab or Enter |
| Press | { "type": "press", "key": "Enter" } | One character, or Enter, Tab, Escape, Backspace, Delete, Insert, Home, End, PageUp, PageDown, an arrow key (ArrowDown), Space or F1 to F12, after at most three distinct Control, Shift, Alt or Meta modifiers, as in Control+K |
Selectors are CSS, up to 200 characters, with no control characters. Scrolling moves at most 100,000 pixels in all, with a direction step counted as 4,096. A wait supplies exactly one of milliseconds or selector. Unknown fields and action types are refused. Screenshot and scrape steps, which capture the page partway through a sequence, belong to the Web API's read and scrape, which return their captures; this endpoint refuses them.
Actions keep every guard navigation has: DNS and address checks, the resource and transfer limits, and the method guard. Only GET requests leave the browser, so a click can follow a link, open a tab or submit a search form that uses GET, but a form that POSTs, a sign-in or a purchase fails with navigation_blocked and never reaches the destination. The API runs no caller-provided JavaScript.
This illustrative request accepts a consent banner, searches, and waits for the results:
{
"url": "https://example.com/filings",
"render": true,
"output": "json",
"actions": [
{ "type": "click", "selector": "#accept-cookies" },
{ "type": "write", "selector": "input[name=q]", "text": "Q3 2026" },
{ "type": "press", "key": "Enter" },
{ "type": "wait", "selector": "#results" }
],
"timeoutMs": 30000
}An action that runs out of time returns action_timeout; invalid CSS returns invalid_selector; an action the page cannot take returns action_failed. A failure during the sequence, including a navigation a step caused, names that step, counted from 0:
{ "error": { "code": "navigation_blocked", "message": "...", "statusCode": null, "action": { "index": 1, "type": "click" } } }Every output travels in a JSON envelope. This example is illustrative:
{
"url": "https://example.com/",
"finalUrl": "https://example.com/",
"statusCode": 200,
"title": "Example Domain",
"output": "text",
"content": "Example Domain Illustrative page content.",
"meta": {
"requestId": "illustrative-request-id",
"delivered": true,
"rendered": true,
"durationMs": 1500,
"attempts": [{"attempt": 1, "outcome": "delivered", "route": "direct", "network": "direct", "browser": "chromium"}],
"network": {"requests": 1, "blockedRequests": 0, "transferredBytes": 1200, "connectionFailures": 0},
"challenge": {"detected": false, "cleared": false, "waitedMs": 0, "verificationRequests": 0, "interactions": 0}
}
}The receipt carries measured duration, request count, and encrypted tunnel bytes. Bytes include protocol overhead and both directions. delivered is a delivery observation; the alpha has no billing implementation.
Refusals and retries
Recognized challenge pages receive up to 12 seconds per attempt for the page's JavaScript verification to complete. Detection uses Cloudflare's cf-mitigated: challenge response header or specific challenge titles and markup. The service keeps the same session while verification runs, then checks the latest main-page response and rendered content. A visible Cloudflare verification checkbox can receive at most two interactions during the wait. The service does not interact with arbitrary page forms or solve image puzzles. render: false refuses a challenge without waiting. Ordinary 403 and 429 responses fail delivery checks and may be retried within the configured attempt budget. A challenge that remains after the wait returns target_challenge.
meta.challenge on delivered responses reports whether a challenge was detected and cleared, the measured wait, and the number of verification requests and widget interactions. Challenge attempts include these fields in their attempt entries, including failed attempts. A successful verification is counted as delivered only after the final HTTP status and content pass delivery checks.
Transient network/proxy failures, incomplete content, and target 5xx responses are retryable. Each attempt uses a new browser. Configured routes rotate unless session selects a sticky route. A block or challenge moves the next attempt up a network tier when the operator configured dearer routes; see Proxy routes. Under the auto profile a challenge also moves the next attempt from Chromium to Camoufox. Each attempt entry names its browser. All attempts share one deadline.
| HTTP | Codes |
|---|---|
| 400 | invalid_request, invalid_browser_options, country_unavailable, network_unavailable, destination_blocked before admission, session_owner_required |
| 401 | unauthorized |
| 404 | not_found for an unknown path |
| 405 | method_not_allowed |
| 413 | invalid_request for an oversized request body |
| 415 | unsupported_media_type |
| 429 | rate_limited, daily_limit, page_limit (shared quota page attempts), service_busy, session_busy, session_capacity |
| 499 | request_cancelled |
| 500 | internal_error when the service cannot prepare a response |
| 502 | target_blocked, target_challenge, target_http_error, target_unreachable, target_incomplete, proxy_unavailable, destination_blocked, navigation_blocked, action_failed, selector_timeout, invalid_selector, request_limit, transfer_limit, page_too_large, target_empty, target_content_type, target_invalid_json, session_state_too_large, session_cleared |
| 503 | browser_unavailable, sessions_unavailable, session_cleanup_unavailable, session_store_unavailable, session_decryption_failed, session_store_invalid, quota_unavailable, service_unavailable while shutting down; website relay: service_not_configured, service_unavailable |
| 504 | target_timeout, action_timeout, session_cleanup_timeout, upload_timeout for a request body not received in time |
API failure responses include the request ID and attempt outcomes after admission. A challenge is never intentionally returned as a delivered page. Header detection is explicit; title and markup detection is heuristic. The alpha cannot promise detection of every anti-bot system, image CAPTCHA solving, or success on every site. Outcomes depend on the browser runtime and route. Cloudflare does not support automated browsers for solving production challenges; passing a demonstration target is not a general success guarantee.
Sessions and network scope
Every attempt has a fresh browser and loopback CONNECT proxy. session keeps proxy selection stable while the operator's route list stays unchanged. persistSession defaults to false, so a session identifier alone leaves each attempt's cookies and storage fresh. Explicit persistSession: true restores and saves cookies and localStorage for the authenticated client and session identifier after successful delivery and browser/network cleanup. Keys mapped to the same client identifier share that client's session namespace.
State is RAM-only: 15-minute sliding TTL after each successful save, 100 sessions total, 20 per client, and 256 KiB of serialized state per session in the standalone startup. Expired state is discarded when the session store is next accessed. Restart loses this state. No idle browser is retained. sessionStorage, IndexedDB, the live DOM, open connections, and page JavaScript state are not restored. Failed or cancelled attempts preserve the previous saved snapshot. An oversized replacement returns session_state_too_large. Concurrent same-session persistence returns session_busy; exhausted total or per-client capacity returns session_capacity.
To reuse a page's own cookies and localStorage, send the same authenticated client, session identifier, and explicit persistence option on each request:
{
"url": "https://example.com/catalog",
"render": true,
"output": "json",
"session": "catalog-01",
"persistSession": true,
"waitFor": "main"
}DELETE /v1/sessions/SESSION_ID authenticates with the API key and clears only the caller's saved session. It accepts no query parameters or request body and consumes admission quota. Clearing an active persistent session cancels its attempt and waits for browser cleanup before returning:
curl -X DELETE https://unblock.vitna.ai/v1/sessions/catalog-01 \
-H "Authorization: Bearer $VITNA_UNBLOCKER_KEY"{ "session": "catalog-01", "cleared": true }An absent or expired session returns cleared: false. The cancelled render cannot save late state. If a clear request is cancelled before dispatch, it does not change the session. If it is cancelled while waiting for active cleanup, the cleanup still settles and the previous committed snapshot is retained when it has not expired; retry the clear request to remove it.
Callers can set the two bounded headers listed above. Credentials, cookies, proxy URLs, arbitrary headers, and browser scripts cannot be supplied. The page can issue public HTTPS GET requests for scripts, styles, and data. After observing a main-page challenge, the service also allows verification POSTs from fetch/XHR and verification images under /cdn-cgi/challenge-platform/ on that page's origin, challenges.cloudflare.com, and its subdomains. There are at most 20 verification POSTs/images per attempt, with POST bodies capped at 128 KiB. A Cloudflare challenge can also hand back the main page through a URL-encoded verification POST to the same origin and path, preserving application query parameters. Only token-shaped verification fields are accepted, with at most eight unique fields. This requires an observed cf-mitigated: challenge main-page response. Other form navigations return navigation_blocked. Handoff requests share the verification count and body limits. These requests count toward the overall resource budget and retain all DNS, HTTPS, host scope, and transfer checks. Application POSTs, other methods, ordinary images, fonts, media, downloads, and WebSockets are blocked; service workers are disabled. Workflows that require application POST data loading are outside this alpha contract.
An unavailable secondary resource increases meta.network.connectionFailures without replacing a usable page's result. A failed main navigation still fails delivery. Private DNS answers and transfer budget violations fail the attempt.
Public DNS addresses are validated and pinned into the actual TCP connection. IP literals, internal names and addresses, credential-bearing URLs, HTTP, custom ports, and private redirects are refused. The browser retains its native TLS, certificate verification, and original hostname/SNI. A Chromium sandbox is enabled. Deploy the service as its own unprivileged process with the supplied memory and CPU limits.
Encrypted restart persistence and shared quotas
Named sessions remain in RAM by default. Pair VITNA_UNBLOCKER_SESSION_DATA with an exact 32-byte hexadecimal VITNA_UNBLOCKER_SESSION_KEY_HEX to retain encrypted cookies/local storage across restarts. Use a separate private directory from VITNA_UNBLOCKER_DATA; requests still require persistSession:true. AES-256-GCM binds each stored state to its tenant, session, expiry and byte bounds. A key that opens no stored row fails startup closed and changes nothing. Modified ciphertext is never used or overwritten: when the key opens other rows, startup moves the damaged row aside unchanged under a browser-session-quarantine:v1: key and logs the count, and at runtime it fails only its own session, which its owner can still delete. Each request decrypts only its own session's row. Deletion, TTL and per-client/global limits survive restart. Storage closes after physical browser cleanup, preserving successful state.
Existing POSIX directories/files must be privately owned by the service user; Windows deployments must supply private ACLs. Directory/data links and hardlinked databases are rejected. Retain the operator key separately from a consistent database backup. Rotation and replicated session storage are not implemented.
For multiple standalone API processes, explicitly configure VITNA_UNBLOCKER_QUOTA_BACKEND=shared, VITNA_UNBLOCKER_QUOTA_URL and VITNA_UNBLOCKER_QUOTA_TOKEN to use the owned quota authority. Its service limits govern both API requests and each browser attempt, including retries. Status reports shared limits and counters; unavailable admission fails closed without automatic retries or local fallback. One authority writer coordinates quota over durable SQLite, while browser concurrency and sessions remain local. See shared Web quota setup and deploy/vitna-quota.env.example. Local quotas remain the default.
Proxy routes
Direct connections work without a proxy account. An operator can configure HTTP or HTTPS CONNECT proxies in the service's private environment:
VITNA_UNBLOCKER_PROXIES=["https://user:[email protected]:8443","http://user:[email protected]:8080"]To expose country selection, label the configured routes:
VITNA_UNBLOCKER_PROXY_ROUTES=[{"id":"us-primary","country":"US","proxy":"https://user:[email protected]:8443"},{"id":"gb-primary","country":"GB","proxy":"https://user:[email protected]:8443"}]The request then selects one of those labels:
{
"url": "https://example.com/",
"country": "US",
"session": "price-watch-01",
"language": "en-US",
"viewport": { "width": 1440, "height": 960 },
"headers": { "dnt": "1" }
}The lists accept up to 20 proxy URLs and 100 entries in all. A country request uses only routes that serve that country and fails with country_unavailable when none does. Without a session, selection cycles through the eligible configured routes. With a session, its identifier deterministically selects the same eligible route while that list stays unchanged. Vitna does not verify the provider's physical location or supply a proxy network.
Residential and ISP provider routes
A route can also come from a residential, ISP, or datacenter proxy account the operator holds. Give it a kind and credential templates in place of fixed credentials:
VITNA_UNBLOCKER_PROXY_ROUTES=[{"id":"dc-us","country":"US","proxy":"https://user:[email protected]:8443"},{"id":"residential","kind":"residential","countries":"*","proxy":"http://gateway.provider.example:7000","session":{"username":"customer-ACCOUNT[-country-{country}]-session-{session}","password":"PASSWORD"}}]| Field | Meaning |
|---|---|
kind | datacenter (the default), isp, or residential |
country | The one uppercase two-letter country a route serves |
countries | "*" or a list of uppercase codes the provider can target; requires {country} or {COUNTRY} in a template |
session | username and password templates, each 1 to 512 characters |
In a template, {session} becomes a token for the attempt: a fresh one each time, so each attempt can leave from a new address, or, when the request names a session, one derived from the client and that session, so the provider can keep its address. The request's session name never reaches the provider. {country} and {COUNTRY} become the requested country in lower and upper case. A [...] segment is kept only when every placeholder in it has a value, which is how a template serves requests that name no country. A template with {country} outside a segment serves only requests that name one. Vitna assumes no provider syntax beyond this: write the username format your provider documents into the template.
Attempts start on the cheapest network configured. A block, challenge, or HTTP error from the target moves the next attempt up a tier, from datacenter to ISP to residential, within the request's retries; other failures retry on the same tier. A request can name a tier with network, and fails with network_unavailable when no route of that kind serves it. A route whose proxy refuses the connection rests for a minute while the others serve. Each attempt entry names its route and network.
Credentials are percent-encoded URL credentials. They stay inside the connector and never enter receipts or API responses. Proxy providers must support CONNECT to a pinned public IP; TLS still uses the target's original hostname. Network access and proxy capacity remain the operator's infrastructure.
Run an owned egress gateway
Run Vitna's CONNECT server on an operator-controlled machine. It needs no proxy provider API. Keep the password private and create a credential hash from environment variables:
npm run egress:hashThe command reads VITNA_EGRESS_USERNAME and VITNA_EGRESS_PASSWORD, then prints only SHA-256 of username:password. The username uses 1 to 64 letters, numbers, dots, underscores, or hyphens; the password is 16 to 256 characters without control characters. Store the hash in an ignored egress configuration file, rather than its plaintext password:
VITNA_EGRESS_OPERATORS={"browser":"REPLACE_WITH_PRINTED_CREDENTIAL_HASH"}
VITNA_EGRESS_HOST=127.0.0.1
VITNA_EGRESS_PORT=8791node --env-file=.env.egress platform/unblocker/egress-start.mjsWith settings already in the environment, use:
npm run egress:startConfigure a browser service's private upstream URL using that username and URL-encoded password. The examples are placeholders:
VITNA_UNBLOCKER_PROXY_ROUTES=[{"id":"owned-us","country":"US","proxy":"https://browser:[email protected]:8791"}]
# The Web suite uses the same route shape.
VITNA_WEB_PROXY_ROUTES=[{"id":"owned-us","country":"US","proxy":"https://browser:[email protected]:8791"}]The gateway binds to loopback HTTP by default. For HTTPS CONNECT, configure both VITNA_EGRESS_TLS_KEY_FILE and VITNA_EGRESS_TLS_CERT_FILE with the operator's PEM files. Match the upstream URL scheme to the configured listener. Operators authenticate with Basic Proxy-Authorization, which plain HTTP carries readable, so startup refuses any VITNA_EGRESS_HOST other than 127.0.0.1, ::1, or localhost unless both TLS files are configured; the supplied Dockerfile binds loopback for the same reason. A regular website reverse proxy may not support forwarding CONNECT tunnels.
Only authenticated CONNECT to public destinations on port 443 is accepted. DNS results must all be public; the connection pins the checked public address. Private targets and other ports are refused. Browser requests already pin their upstream CONNECT destination to a public IP, so an egress hostname-only allowlist does not match those tunnels. If restricting the gateway, list the explicit public IPs the browser will use, or leave the allowlist empty for public destinations. Canonical IPv6 entries use brackets. GET /healthz reports only process health; other ordinary HTTP methods return 405. The gateway does not terminate the target website's TLS.
| Environment | Default | Meaning |
|---|---|---|
VITNA_EGRESS_ALLOWED_HOSTS | All public destinations | Comma-separated exact public hostnames or IPs |
VITNA_EGRESS_CONCURRENCY | 32 | Active CONNECT tunnels |
VITNA_EGRESS_QUEUE_LIMIT | 64 | Waiting authenticated tunnels |
VITNA_EGRESS_CONNECTION_LIMIT | 128 | Accepted client sockets, including incomplete headers |
VITNA_EGRESS_MAX_BYTES | 20,971,520 | Per-tunnel bytes in both directions |
VITNA_EGRESS_TUNNEL_TIMEOUT_MS | 60,000 | Whole tunnel deadline |
VITNA_EGRESS_CONNECT_TIMEOUT_MS | 10,000 | DNS and connection deadline |
VITNA_EGRESS_QUEUE_TIMEOUT_MS | 5,000 | Maximum queue wait |
VITNA_EGRESS_HEADER_TIMEOUT_MS | 5,000 | Request header deadline |
Place owned nodes in the regions your workloads need and label their routes in the browser configuration. Country labels describe the operator's routing choice; Vitna does not verify location or provision regional machines, IP capacity, or a residential network. Limits apply to each gateway process. The supplied deploy/vitna-egress.env.example, deploy/vitna-egress.service, and deploy/vitna-egress.Dockerfile prepare an operator deployment; they do not provision or publish a gateway.
Sell proxy access from a gateway
A gateway can also carry customers' own traffic on proxy keys their accounts mint, once it is joined to the Web coordinator that holds those accounts. Mint the gateway's token, give the gateway the token and the coordinator's origin, and give the coordinator the token's hash:
npm run egress:gateway-key# The gateway
VITNA_EGRESS_ACCOUNTS_URL=https://web.example.com
VITNA_EGRESS_GATEWAY_TOKEN=vitna_gateway_PRINTED_TOKEN
VITNA_EGRESS_HOST=0.0.0.0
VITNA_EGRESS_TLS_KEY_FILE=/run/secrets/egress.key
VITNA_EGRESS_TLS_CERT_FILE=/run/secrets/egress.crt
# The Web coordinator
VITNA_WEB_PROXY_GATEWAYS=[{"id":"egress-de","tokenHash":"PRINTED_HASH","endpoint":"egress-de.example.com:8791","country":"DE"}]Customers sign in as ACCOUNT:vitna_proxy_...; accounts and grants are covered in proxy access. The gateway asks the coordinator about a key and keeps the answer for 30 seconds. While the coordinator cannot be reached, during a deploy for example, it keeps an allowed answer for up to five minutes. Every minute it reports the bytes each account moved, as running totals for the hour. The coordinator settles each hour into the account's ledger 15 minutes after the hour ends. A gateway that stops loses at most its last minute of counting, which is never billed. Operator credentials keep working alongside customers', and VITNA_EGRESS_OPERATORS may be empty on a gateway that serves only customers. Customer tunnels share the gateway's VITNA_EGRESS_CONCURRENCY and VITNA_EGRESS_CONNECTION_LIMIT. Raise those limits for customer traffic, or run separate gateways so customers cannot crowd out your own browsers.
For customers, the gateway enforces:
- HTTPS only. CONNECT to port 443 of a public address, checked and pinned as for operators. There is no plain HTTP and no other port, so no mail.
- The account's grant. Tunnels open at once, tunnels started per minute, and the month's bytes. When the allowance runs out, the gateway closes all of the account's open tunnels.
- Blocked hosts.
VITNA_EGRESS_BLOCKED_HOSTSlists hosts customers may not reach; each entry also covers every name under it. - Tunnel limits. Bytes, total lifetime and idle time, set by the
VITNA_EGRESS_CUSTOMER_*settings below. - Failed sign-ins. After 30 failed sign-ins in a minute from one network (an IPv4 /24 or IPv6 /64), customer sign-ins from that network answer 429 until the minute ends, and the coordinator is not asked. Operators are never held back.
- Revocation. Open tunnels are checked again every 30 seconds as their answers age, so a revoked key or a suspended account loses its tunnels within about a minute.
A refusal names its reason in an X-Vitna-Error header:
| HTTP | X-Vitna-Error |
|---|---|
| 403 | proxy_access_suspended, proxy_access_not_granted, monthly_allowance_exhausted, destination_blocked |
| 407 | None: the account or key is not valid |
| 429 | concurrency_limit, tunnel_rate_limit, authentication_rate_limited |
| 503 | accounts_unavailable when the coordinator cannot answer |
Each customer tunnel writes one JSON line to standard output, with event set to customer_tunnel and the fields at, client, host, bytes, durationMs, and outcome. It records the account, the destination host and the volume, which is what an abuse report needs. It never records content, URLs, or the key. Under systemd the journal keeps these lines; set its retention (MaxRetentionSec=) to match your policy. The gateway limits what a customer can do. It does not vet who the customer is: that check happens when you grant access.
| Environment | Default | Meaning |
|---|---|---|
VITNA_EGRESS_ACCOUNTS_URL | Unconfigured | The Web coordinator's HTTPS origin (loopback HTTP on one machine); with the token, serves customer proxy keys |
VITNA_EGRESS_GATEWAY_TOKEN | Unconfigured | This gateway's vitna_gateway_ token |
VITNA_EGRESS_BLOCKED_HOSTS | None | Comma-separated lowercase hosts or IPs customers may not reach, each with every name under it |
VITNA_EGRESS_CUSTOMER_MAX_BYTES | 1,073,741,824 | Per customer tunnel, both directions |
VITNA_EGRESS_CUSTOMER_TUNNEL_TIMEOUT_MS | 600,000 | Whole customer tunnel deadline |
VITNA_EGRESS_CUSTOMER_IDLE_TIMEOUT_MS | 120,000 | Customer tunnel time without a byte |
VITNA_EGRESS_SIGN_IN_FAILURES_PER_MINUTE | 30 | Failed sign-ins per network per minute before 429 |
Browser profiles and live checks
The default native profile uses the installed or bundled Chromium runtime. An optional cloakbrowser profile uses an operator-installed CloakBrowser executable with its fingerprint flags and desktop viewport defaults. Requests can select a different viewport within the common limits. It retains the Chromium sandbox, certificate checks, guarded proxy, and request limits. The profile requires VITNA_UNBLOCKER_BROWSER_PATH; no vendor binary is bundled, downloaded at service startup, or substituted automatically.
VITNA_UNBLOCKER_BROWSER_PROFILE=cloakbrowser
VITNA_UNBLOCKER_BROWSER_PATH=/opt/cloakbrowser/chromeThis profile was locally verified with CloakBrowser 146 against the public Cloudflare and Antibot demonstration pages. The native Edge runtime on the same machine remained challenged. Other versions and deployment platforms need their own verification. CloakBrowser's binary license requires a separate OEM/SaaS agreement for customer-facing browser API use; an internal test does not provision that agreement or a hosted service.
The camoufox profile
The camoufox profile renders in Camoufox, the Firefox build Search's Google collector already runs, and is the one profile measured to clear the challenge demonstrations without a licence agreement. On 2026-10-16, on one Windows desktop with no proxy, hardened Chromium that passed every Sannysoft test still held 0 of 6 challenge attempts, while Camoufox cleared 18 of 20 in a standalone trial and, through this service's own guarded proxy, 18 of 20 one at a time and 14 of 20 four at a time (Measured on 2026-10-16).
Camoufox's fingerprints come from its Python package, so the host needs a Python with that package and its browser fetched, pinned as Search pins them:
python3 -m venv /opt/vitna-camoufox
/opt/vitna-camoufox/bin/pip install "camoufox[geoip]==0.5.7"
/opt/vitna-camoufox/bin/python -m camoufox fetchVITNA_UNBLOCKER_BROWSER_PROFILE=camoufox
VITNA_UNBLOCKER_CAMOUFOX_PYTHON=/opt/vitna-camoufox/bin/python
VITNA_UNBLOCKER_CAMOUFOX_FINGERPRINTS=8camoufox fetch puts the browser in the cache directory of the user who runs it, so run it as the service's user, and give the service the same XDG_CACHE_HOME when its HOME does not last, as a systemd runtime directory does not. For the hosted service, deploy/web-api/install-camoufox.sh does both and checks the result under the unit's confinement (deploy/web-api/OVH-RUNBOOK.md, The auto browser profile).
At startup the service runs platform/unblocker/camoufox-options.py once for that many fingerprints (1 to 32, 8 by default) and refuses to start if it cannot. Attempts take turns over them; a request that names a session keeps one, so a persisted session's cookies return to the browser that earned them. The helper runs with only the environment it needs to find Python and Camoufox's cache, and only Camoufox's own CAMOU_CONFIG_n and CAMOU_PREFS_n keys reach the browser: Camoufox's launch options copy the whole process environment, and the service refuses any other key.
Firefox has no launch flags for what the Chromium profiles enforce with them, so the profile sets preferences that no fingerprint can override: every connection, loopback names included, goes through this attempt's guarded proxy, which resolves names, refuses private answers and pins the public address, and none falls back to a direct connection; DNS-over-HTTPS, prefetching, speculative connections and QUIC are off, and WebRTC carries no UDP outside the proxy. Printing a page to PDF and reading a document's response are Chromium's alone and are refused on this profile; the public Unblocker uses neither. It is slower: four at a time on one desktop, its median page took 3 to 8 seconds where Chromium's took about one, so it suits pages that sit behind a browser check rather than every page.
The camoufox package is MIT-licensed by its package metadata (read 2026-10-16). The browser it fetches is a Firefox build with no licence file of its own; review its terms before selling access through it, as for any browser this service runs.
VITNA_UNBLOCKER_CAMOUFOX_OS limits the fingerprints to a comma list of windows, macos and linux; unset, Camoufox chooses among all three. On a Windows host on 2026-10-16, Windows-only fingerprints cleared the challenge demos as often as mixed ones (18 of 20 each, one at a time) at half the median time, 4.7 seconds against 9.7, so measure a host with its own operating system before choosing.
The auto profile
auto reads every page in Chromium and moves a request to Camoufox only after a challenge has held it, so ordinary pages keep Chromium's speed and a page behind a browser check still clears:
VITNA_UNBLOCKER_BROWSER_PROFILE=auto
VITNA_UNBLOCKER_CAMOUFOX_PYTHON=/opt/vitna-camoufox/bin/pythonUnder auto the first attempt reads in Chromium. If it meets a challenge it does not wait one out, since Chromium has cleared none of the demonstrations it met; it ends at once with target_challenge, and the next attempt reads in Camoufox with the full challenge wait. The step uses the request's own retries, so it needs at least one (the default); with retries: 0 a challenged page ends target_challenge after the Chromium attempt. A block that is not a challenge steps the network tier and stays in Chromium. A capture stays in Chromium, which alone prints it. The Web API's reads, which also take a document a URL serves, move as pages do. Firefox has no response interception, so Camoufox takes such a document from its navigation's own response, which Playwright keeps once the context accepts downloads; only those reads accept them. This service's own reads never take a document, so Camoufox still refuses one here as target_content_type. If Camoufox cannot be readied when the service starts, auto starts on Chromium alone and logs the reason in one line, so a broken Camoufox install costs the step up rather than the service; the camoufox profile refuses to start instead. On Linux, Camoufox's fingerprints carry the FONTCONFIG_FILE it writes for the operating system they claim, which the browser is given beside the CAMOU_ keys. Each attempt entry says which browser it used:
{ "attempts": [
{ "attempt": 1, "outcome": "target_challenge", "statusCode": 403, "browser": "chromium" },
{ "attempt": 2, "outcome": "delivered", "browser": "camoufox" }
] }Run the explicit live check using the same browser and proxy settings as the service. It creates a temporary local API key, sends authenticated HTTP requests to a local process, verifies page content, and exits:
npm run unblocker:check
npm run unblocker:check -- outputs/unblocker-check.json
npm run unblocker:check -- --extended outputs/unblocker-extended-check.jsonThe check contacts https://quotes.toscrape.com/js/, https://www.scrapingcourse.com/cloudflare-challenge, and https://www.scrapingcourse.com/antibot-challenge. It exits unsuccessfully if any target is not delivered with its expected content. Default unit tests use fixtures and do not contact these websites.
The --extended suite adds JavaScript-disabled comparisons, JavaScript pagination, a 10-second rendering delay, AJAX quotes, AJAX products, two fresh attempts per challenge page, and Sannysoft fingerprint diagnostics. It verifies rendered item counts and readable content, excluding inline scripts from item counts. The product check waits for the last populated product name; the page's initial empty product cards are loading placeholders.
The delayed-page control deliberately omits waitFor to exercise automatic readiness. Stable visible page content does not establish that delayed quote items are ready; a persistent empty or loading state fails with target_incomplete. The matching selector case waits for all 10 quotes. The AJAX quote check covers the initial batch; it does not scroll or click to collect further batches.
Fingerprint diagnostics report each detection test separately in detectionTests and detectionPassed. The report's passed field describes delivery and content assertions, including the controls; it does not mean every fingerprint detector was passed or establish protection against other anti-bot systems. Reports omit API keys, raw page content, and fingerprint values.
Comparing with Bright Data
An explicit comparison runner sends the same four public pages through the local authenticated Vitna HTTP API and Bright Data's Web Unlocker REST API. It covers immediate JavaScript, a 10-second JavaScript delay, and the two challenge demonstrations. Two rounds alternate provider order, with at most eight Bright Data requests. These requests use your existing account and may be billable under its plan; the runner does not create a zone or change account settings.
Set BRIGHTDATA_API_KEY and BRIGHTDATA_UNLOCKER_ZONE in an ignored local .env.brightdata file. Configure Vitna's browser settings in the environment as for the live check, then run:
node --env-file=.env.brightdata platform/unblocker/benchmark.mjs outputs/unblocker-benchmark/comparison.json
npm run unblocker:benchmark -- --vitna-only outputs/unblocker-benchmark/vitna-baseline.jsonThe second command runs only the Vitna baseline. Its report explicitly marks Bright Data as not_run and comparisonComplete as false. The default comparison refuses to send requests when either Bright Data credential is missing, and stops further provider requests on authentication, configuration, quota, or malformed-response errors.
Timing covers the caller's entire request through the complete decoded response body. Both providers must return the expected readable content and populated item counts, with no remaining challenge. An HTTP 200 containing only JavaScript source or an empty loading page fails verification. Reports exclude credentials, provider zone identifiers, response headers, raw HTML, and cookies. Average latency includes only content-verified responses and must be read alongside success counts.
Vitna uses an explicit waitFor selector and a fresh browser per request; the default comparison uses Bright Data's automatic behavior without custom headers. The provider's browser, retries, session reuse, proxy route, and cache state are unobserved. This small demo comparison includes local versus remote API transport overhead and does not establish production performance or isolate JavaScript challenge-solving time.
The bulk runner uses ten pages from three public training-site domains: five JavaScript/AJAX pages, three static controls, and two challenge demos. Its default is four rounds (40 attempts per provider) with four requests in flight per provider. Both provider batches start together; each has its own bounded queue. Page order rotates each round.
node --env-file=.env.brightdata platform/unblocker/bulk-benchmark.mjs outputs/unblocker-benchmark/bulk.json
npm run unblocker:bulk -- --vitna-only --rounds 4 --concurrency 2 outputs/unblocker-benchmark/bulk-vitna.json--rounds accepts 1–10 and --concurrency accepts 1–4. These cap each provider at 100 attempts; the default comparison uses at most 40 billable Bright Data requests. Failed account/configuration requests stop further scheduling; already-started requests settle. Interrupting the runner aborts in-flight calls and preserves a partial report. No failed request is retried.
For a browser-rendering comparison, --brightdata-render sends the documented `render: "true"` parameter to Bright Data. --javascript-only selects the five JavaScript/AJAX targets for a smoke test. --timeout-ms accepts 1,000–60,000 and sets the same caller deadline for both APIs, plus Vitna's request and ephemeral service deadline. Without that option, the original 35-second caller and 30-second Vitna deadlines remain. The report records forced rendering and the deadlines.
With credentials and browser settings already in the environment:
npm run unblocker:bulk -- --brightdata-render --javascript-only --rounds 1 --timeout-ms 60000 outputs/unblocker-benchmark/smoke-rendered.json
npm run unblocker:bulk -- --brightdata-render --rounds 10 --timeout-ms 60000 outputs/unblocker-benchmark/bulk-rendered-100.jsonThe smoke uses at most five Bright Data requests; the full run uses at most 100. Run the smoke before the larger workload. Forced rendering retains Bright Data's automatic readiness rather than Vitna's explicit selectors, and its browser, routes, cache, and internal retries remain unobserved.
Each provider's batch reports content-verified throughput, p50 and p95 latency using nearest rank, failure counts, and results by static, JavaScript, and challenge category. Latency for verified pages and latency for all attempts are recorded separately. An empty JavaScript shell remains a content failure even if its API request returned quickly.
The isolated benchmark service admits 120 requests per minute and uses the requested browser concurrency. These are benchmark configuration values; they do not change another running service's quotas or capacity. Repeating these ten pages tests consistency and resource contention within this workload; it does not expand the suite's coverage of production websites.
Measured on 2026-10-16
The full Vitna-only run (--vitna-only --rounds 10 --concurrency 4 --timeout-ms 60000), on one Windows x64 desktop with the native Edge profile and no proxy, is the largest Unblocker run on record: unblocker-bulk-100-20261016.json.
| Pages | Verified | Verified p50 | Verified p95 |
|---|---|---|---|
| Static, 30 | 30 | 0.89 s | 1.44 s |
| JavaScript, 50 | 50 | 1.12 s | 11.5 s, the page that waits 10 seconds |
| Challenge demos, 20 | 0 | ||
| All, 100 | 80 | 1.07 s | 11.4 s |
The 100 took 117 seconds with four browsers in flight, 0.69 verified pages a second. Every challenge attempt ended target_challenge after the 12-second wait. The extended live check the same evening (unblocker-extended-check-20261016.json) agrees: all four attempts at the two challenge demos stayed challenged, each after two widget interactions and ten verification requests, and Sannysoft flagged 4 of its 31 fingerprint tests. It also shows the limit of automatic readiness: the 10-second delayed page without waitFor was returned as delivered holding none of its 10 quotes, so name a selector for content that arrives late.
The same run on the camoufox profile that evening (unblocker-bulk-camoufox-100-20261016.json):
| Pages | Native, verified | Camoufox, verified | Camoufox p50 | Camoufox p95 |
|---|---|---|---|---|
| Static, 30 | 30 | 30 | 3.33 s | 11.3 s |
| JavaScript, 50 | 50 | 50 | 5.56 s | 20.9 s |
| Challenge demos, 20 | 0 | 14 | 7.97 s | 28.5 s |
| All, 100 | 80 | 94 | 5.69 s | 17.5 s |
It took 220 seconds, 0.43 verified pages a second. Each of the six misses ended target_challenge, mostly in the first round, while four Firefox browsers were starting at once on one desktop. One at a time, as the hosted service runs (VITNA_UNBLOCKER_CONCURRENCY=1), the two demos ten times each cleared 18 of 20 at the default 12-second wait. The extended live check on the same profile (unblocker-extended-check-camoufox-20261016.json) delivered all ten ordinary pages and cleared three of its four challenge attempts; the fourth ran out the 12-second wait. Sannysoft flagged only Chrome (New), which a Firefox build has no reason to pass. The delayed page without waitFor was again delivered with none of its quotes.
The auto profile the next morning (unblocker-bulk-auto-100-20261017.json), same pages and settings with Windows fingerprints and the one retry its step needs (--retries 1), delivered all 100: static 30 of 30 at a 1.00-second median, JavaScript 50 of 50 at 1.21 seconds, and challenge demos 20 of 20 at 6.97 seconds. It took 89 seconds, 1.13 verified pages a second, faster than the native run's 117, because Chromium no longer waits out a challenge it cannot clear. The extended live check on it (unblocker-extended-check-auto-20261017.json) cleared three of four challenge attempts at about 5.5 seconds each; the fourth ran out Camoufox's 12-second wait. Its Sannysoft row reads Chromium's four flags, rightly: that page sets no challenge, so auto never leaves Chromium for it.
These are training pages on one machine. They say nothing about production websites, the hosted service's capacity, or a proxy or CloakBrowser profile, which these runs did not use.
Configuration and status
| Environment | Default | Meaning |
|---|---|---|
VITNA_UNBLOCKER_CLIENTS | Required | JSON client identifier to SHA-256 token hash |
VITNA_UNBLOCKER_HOST | 127.0.0.1 | Listening interface |
VITNA_UNBLOCKER_PORT | 8788 | Listening port |
VITNA_UNBLOCKER_DATA | .unblocker-data | Standalone SQLite WAL directory for admission counters; separate from Web account/job state |
VITNA_UNBLOCKER_METRICS_TOKEN_HASH | Unconfigured | Lowercase 64-character SHA-256 hash of an operator metrics token; enables authenticated GET /metrics |
VITNA_UNBLOCKER_RPM | 20 | Per-client requests per UTC minute |
VITNA_UNBLOCKER_DAILY_LIMIT | 1,000 | Per-client requests per UTC day |
VITNA_UNBLOCKER_CONCURRENCY | 2 | Browser requests in flight per process |
VITNA_UNBLOCKER_TIMEOUT_MS | 30,000 | Maximum total deadline, up to 60,000 |
VITNA_UNBLOCKER_CHALLENGE_WAIT_MS | 12,000 | Maximum verification wait per attempt, 0 to 20,000; 0 disables waiting |
VITNA_UNBLOCKER_PROXIES | [] | Private ordered CONNECT proxy URLs |
VITNA_UNBLOCKER_PROXY_ROUTES | [] | Private route objects with a unique id and proxy URL, and optionally kind, country or countries, and session credential templates |
VITNA_UNBLOCKER_ALLOWED_HOSTS | All public hosts | Optional comma-separated exact hosts, including required asset hosts |
VITNA_UNBLOCKER_BROWSER_CHANNEL | Bundled Chromium | Optional installed browser channel, such as msedge |
VITNA_UNBLOCKER_BROWSER_PATH | Playwright default | Optional operator-selected executable path |
VITNA_UNBLOCKER_BROWSER_PROFILE | native | native, cloakbrowser (requires an installed executable path), camoufox or auto, Chromium first and Camoufox after a challenge (both require the Python below) |
VITNA_UNBLOCKER_CAMOUFOX_PYTHON | Unconfigured | camoufox and auto: a Python with the camoufox package installed and its browser fetched |
VITNA_UNBLOCKER_CAMOUFOX_FINGERPRINTS | 8 | camoufox and auto: fingerprints made at startup, 1 to 32 |
VITNA_UNBLOCKER_CAMOUFOX_OS | All three | camoufox and auto: comma list of windows, macos, linux the fingerprints may claim |
VITNA_UNBLOCKER_SERVICE_URL | Unconfigured | Website process only: destination for its relay |
The request body is capped at 8 KiB. A page has at most 400 allowed intercepted resource requests, 20 MiB of tunnel transfer, and 2 MiB of serialized HTML. Chromium also bounds HTTP redirect chains. Startup stores admission counters in VITNA_UNBLOCKER_DATA (default .unblocker-data) with SQLite WAL transactions. Keep this volume across restart and use one writer per directory. Embedded service instances without a store use memory; independent replicas do not share quotas. The directory must differ from Web account/job state. Failures consume admission quota; retries remain one API request. Durable shared quotas are still required before selling usage across replicas.
GET /healthz confirms the HTTP process; it does not launch a browser or verify a proxy account. Authenticated GET /v1/status reports configured limits, current concurrency, configured quota storage, and disabled billing. Receipts log client identity, target hostname, outcome, attempt count, and duration. Receipts omit URL paths/queries, keys, proxy credentials, and fetched content. No search index or raw HTML archive is written. Opted-in cookies and localStorage stay in the bounded RAM session store described above.
Operator metrics
The standalone server uses platform/web/metrics.mjs for authenticated Prometheus text metrics. Generate an operator credential locally:
node platform/web/metrics.mjs --keyThe command prints JSON containing token and hash. Keep the token private for your scraper and configure only its printed hash in the service:
VITNA_UNBLOCKER_METRICS_TOKEN_HASH=REPLACE_WITH_PRINTED_LOWERCASE_SHA256_HASHAfter restarting with that setting, use the printed token as a separate operator bearer credential:
curl http://127.0.0.1:8788/metrics \
-H "Authorization: Bearer $VITNA_METRICS_TOKEN"GET /metrics returns text/plain; version=0.0.4 with Cache-Control: no-store. The endpoint accepts no query parameters or body. It returns 404 when no metrics hash is configured, 401 for missing or invalid operator credentials, and 405 for an authenticated method other than GET. Client API keys do not authorize metrics access.
| Metric | Observation |
|---|---|
vitna_api_http_requests_total | Completed responses by bounded method, operation, and status labels, including errors and metrics scrapes |
vitna_api_http_duration_seconds | Histogram of request time through response transfer, in seconds |
vitna_api_http_in_flight | Current HTTP requests |
vitna_api_browser_active | Browser requests in flight, sampled at HTTP request and response events |
vitna_api_render_attempts_total | Completed render attempts, including failed attempts |
vitna_api_browser_milliseconds_total | Measured render wall time including browser cleanup, not CPU time |
vitna_api_transferred_bytes_total | Tunnel bytes reported by delivered snapshots, including protocol overhead and both directions |
vitna_api_resource_requests_total | Allowed resource requests reported by delivered snapshots |
Metrics carry service="unblocker". Labels exclude client identities, tokens, URLs, hostnames, session identifiers, and fetched content. Series counts are bounded. Metrics are process-local and reset on restart; they are separate from the durable admission counters in VITNA_UNBLOCKER_DATA and do not aggregate independent replicas. Search, model, and priced-usage resource counters stay at zero for this standalone service.
The service uses Playwright Chromium and browser contexts. Challenge handling follows Cloudflare's documented response header and browser support limits. The comparable one-request product shape is described in Bright Data's Web Unlocker documentation.
For operators: run the service yourself
Operator reference. Everything from here down needs the Vitna repository, which is private, and is for the people who run the hosted service. A customer needs none of it: the hosted endpoint and an alpha key are under Hosted access.
Run it locally
The hosted API answers at https://unblock.vitna.ai. Since 2026-10-07 a browser that opens it, or its /docs, is sent to /unblocker and this reference on vitna.ai, where the product's pages live: the operator sets VITNA_UNBLOCKER_PAGE_URL and VITNA_UNBLOCKER_DOCS_URL, and a self-hosted instance with neither set serves its own playground.
The browser service has its own pinned Playwright dependency. It does not share the website database, signing keys, or search index.
npm run unblocker:install
npm run unblocker:browser
npm run unblocker:demoOpen http://127.0.0.1:8788. The demo opens a real Chromium session and executes an illustrative page's JavaScript through the authenticated API. The temporary demo key is filled into the local playground. No target site or paid proxy is contacted. To check that flow and exit:
node platform/unblocker/demo.mjs --checkFor live pages, mint a client key and keep its token private:
npm run unblocker:key -- pilotPut the printed hash, not the token, into an ignored .env.unblocker:
VITNA_UNBLOCKER_CLIENTS={"pilot":"REPLACE_WITH_THE_PRINTED_SHA256_HASH"}
VITNA_UNBLOCKER_PORT=8788Start the live service and open its playground. Paste the token and enter a public HTTPS page:
node --env-file=.env.unblocker platform/unblocker/start.mjsThe equivalent script, when the settings are already in the environment:
npm run unblocker:startThe service binds to loopback by default. TLS termination belongs at a reverse proxy if it is exposed externally. deploy/vitna-unblocker.service, deploy/vitna-unblocker.env.example, deploy/vitna-unblocker.nginx.conf.example, and deploy/vitna-unblocker.Dockerfile prepare a standalone deployment. The hosted service at https://unblock.vitna.ai runs from deploy/web-api/ instead, with its own unit, environment and runbook.
