vitna.ai/docs/unblocker/overview Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/unblocker/overview
> Raw Markdown: https://vitna.ai/docs/unblocker/overview.md
> Corpus index: https://vitna.ai/llms.txt

# 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](https://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](https://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](../one-key.md).
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:

```bash
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](https://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:

```bash
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](#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](https://vitna.ai/start#contact), which is also
where to ask for help.

## Request

The service serves this endpoint, hosted at `https://unblock.vitna.ai`:

```text
POST /v1/unblock
```

The website relays to it. It forwards the caller's key; it has no shared
service key and performs no browser work itself:

```text
POST /api/v1/unblock
```

The 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.

```bash
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`:

```json
{
  "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](../web/overview.md#browser-controls), 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:

```json
{
  "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:

```json
{ "error": { "code": "navigation_blocked", "message": "...", "statusCode": null, "action": { "index": 1, "type": "click" } } }
```

Every output travels in a JSON envelope. This example is illustrative:

```json
{
  "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](#proxy-routes). Under the [auto profile](#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:

```json
{
  "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:

```bash
curl -X DELETE https://unblock.vitna.ai/v1/sessions/catalog-01 \
  -H "Authorization: Bearer $VITNA_UNBLOCKER_KEY"
```

```json
{ "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](../web/overview.md)
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:

```dotenv
VITNA_UNBLOCKER_PROXIES=["https://user:[email protected]:8443","http://user:[email protected]:8080"]
```

To expose country selection, label the configured routes:

```dotenv
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:

```json
{
  "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:

```dotenv
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:

```bash
npm run egress:hash
```

The 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:

```dotenv
VITNA_EGRESS_OPERATORS={"browser":"REPLACE_WITH_PRINTED_CREDENTIAL_HASH"}
VITNA_EGRESS_HOST=127.0.0.1
VITNA_EGRESS_PORT=8791
```

```bash
node --env-file=.env.egress platform/unblocker/egress-start.mjs
```

With settings already in the environment, use:

```bash
npm run egress:start
```

Configure a browser service's private upstream URL using that username and
URL-encoded password. The examples are placeholders:

```dotenv
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:

```bash
npm run egress:gateway-key
```

```dotenv
# 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](../web/overview.md#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_HOSTS` lists 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.

```dotenv
VITNA_UNBLOCKER_BROWSER_PROFILE=cloakbrowser
VITNA_UNBLOCKER_BROWSER_PATH=/opt/cloakbrowser/chrome
```

This 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](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md)
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](https://camoufox.com/python), 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](#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:

```bash
python3 -m venv /opt/vitna-camoufox
/opt/vitna-camoufox/bin/pip install "camoufox[geoip]==0.5.7"
/opt/vitna-camoufox/bin/python -m camoufox fetch
```

```dotenv
VITNA_UNBLOCKER_BROWSER_PROFILE=camoufox
VITNA_UNBLOCKER_CAMOUFOX_PYTHON=/opt/vitna-camoufox/bin/python
VITNA_UNBLOCKER_CAMOUFOX_FINGERPRINTS=8
```

`camoufox 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:

```dotenv
VITNA_UNBLOCKER_BROWSER_PROFILE=auto
VITNA_UNBLOCKER_CAMOUFOX_PYTHON=/opt/vitna-camoufox/bin/python
```

Under `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:

```json
{ "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:

```bash
npm run unblocker:check
npm run unblocker:check -- outputs/unblocker-check.json
npm run unblocker:check -- --extended outputs/unblocker-extended-check.json
```

The 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](https://docs.brightdata.com/products/web-unlocker/send-your-first-request).
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:

```bash
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.json
```

The 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.

```bash
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](https://docs.brightdata.com/products/web-unlocker/features#force-javascript-rendering-with-a-browser)
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:

```bash
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.json
```

The 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](../../deploy/web-api/evidence/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](../../deploy/web-api/evidence/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](#the-camoufox-profile) that evening
([unblocker-bulk-camoufox-100-20261016.json](../../deploy/web-api/evidence/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](../../deploy/web-api/evidence/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-auto-profile) the next morning
([unblocker-bulk-auto-100-20261017.json](../../deploy/web-api/evidence/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](../../deploy/web-api/evidence/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:

```bash
node platform/web/metrics.mjs --key
```

The command prints JSON containing `token` and `hash`. Keep the token private
for your scraper and configure only its printed hash in the service:

```dotenv
VITNA_UNBLOCKER_METRICS_TOKEN_HASH=REPLACE_WITH_PRINTED_LOWERCASE_SHA256_HASH
```

After restarting with that setting, use the printed token as a separate
operator bearer credential:

```bash
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](https://playwright.dev/docs/browsers)
and [browser contexts](https://playwright.dev/docs/api/class-browsercontext).
Challenge handling follows Cloudflare's documented
[response header](https://developers.cloudflare.com/cloudflare-challenges/challenge-types/challenge-pages/detect-response/)
and [browser support limits](https://developers.cloudflare.com/cloudflare-challenges/reference/supported-browsers/).
The comparable one-request product shape is described in
[Bright Data's Web Unlocker documentation](https://docs.brightdata.com/products/web-unlocker/introduction).

## 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](#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.

```bash
npm run unblocker:install
npm run unblocker:browser
npm run unblocker:demo
```

Open `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:

```bash
node platform/unblocker/demo.mjs --check
```

For live pages, mint a client key and keep its token private:

```bash
npm run unblocker:key -- pilot
```

Put the printed hash, not the token, into an ignored `.env.unblocker`:

```dotenv
VITNA_UNBLOCKER_CLIENTS={"pilot":"REPLACE_WITH_THE_PRINTED_SHA256_HASH"}
VITNA_UNBLOCKER_PORT=8788
```

Start the live service and open its playground. Paste the token and enter a
public HTTPS page:

```bash
node --env-file=.env.unblocker platform/unblocker/start.mjs
```

The equivalent script, when the settings are already in the environment:

```bash
npm run unblocker:start
```

The 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.
Human Machine Shift+M