These docs are in English. If you prefer German, write us at beta@clickprobe.ai.

Proxy Connection Troubleshooting

clickprobe-proxy needs to reach a handful of ClickProbe-owned (and Chromium-owned) hosts over plain outbound HTTPS/WSS. This page covers the failure modes that come up behind a corporate network, what the local dashboard is telling you, and where to look next.

Corporate proxy / TLS interception

If your organisation routes outbound traffic through a corporate proxy or does TLS interception (a “man-in-the-middle” inspection appliance re-signing HTTPS with an internal CA), two separate things can go wrong:

1. The corporate proxy itself. clickprobe-proxy is a Go binary — it honors the standard HTTPS_PROXY (and HTTP_PROXY, NO_PROXY) environment variables for its own outbound connections, including the WebSocket tunnel:

export HTTPS_PROXY=http://your-corporate-proxy:8080
clickprobe-proxy

Some corporate proxies block WebSocket upgrade requests even when plain HTTPS is allowed — check with your network team whether wss:// upgrades are permitted on port 443, not just https:// GETs. If they’re categorically blocked, the workaround for now is running the proxy from a machine outside that network boundary (a personal machine, a VPS, a GitHub Codespace) pointed at your app’s staging URL instead of localhost.

2. TLS interception re-signing our cloud’s certificate. If your network appliance re-signs broker.clickprobe.ai / api.clickprobe.ai with an internal CA, the proxy’s Go HTTP client needs that CA in its trust store to avoid a certificate-verification failure. On most platforms, adding the interception CA to your system trust store (not just the browser’s) is enough, since Go’s TLS stack reads from the OS store on macOS/Windows and from the standard ca-certificates bundle on Linux.

The Chromium download

clickprobe-proxy install installs a Playwright driver + a headless Chromium build — together roughly 300 MB — the first time it runs, or after an update. This is the browser the proxy actually launches for every chrome.navigate / screenshot tool call; nothing else in the product substitutes for it.

The driver assembles itself from three sources, not a single Chromium-team CDN:

  1. https://registry.npmjs.org — the playwright-core npm package (override with PLAYWRIGHT_GO_NPM_REGISTRY if your network mirrors npm internally).
  2. https://nodejs.org/dist — a small per-platform Node.js runtime the driver runs on (override with NODE_MIRROR, or skip entirely with PLAYWRIGHT_NODEJS_PATH pointed at a Node.js binary you already have — required on platforms with no prebuilt Node.js, e.g. linux/arm).
  3. https://cdn.playwright.dev — the actual Chromium (and small ffmpeg/headless-shell) archives, resolved by the installed driver version.

Every downloaded archive is verified by the driver before use; a corrupted download is rejected rather than silently used.

If your network blocks any of the above, blocks large downloads outright, or you’re pre-staging machines:

  • clickprobe-proxy install --skip-chromium installs the binary without triggering any browser download, useful for a scripted/offline install where Chromium is provisioned separately.
  • PLAYWRIGHT_CLI_PATH or PLAYWRIGHT_DRIVER_PATH point the driver at a pre-installed driver directory instead of downloading one from npm/nodejs.org — useful for a distro-packaged driver or one prepared on a machine with unrestricted internet access and copied over.
  • PLAYWRIGHT_BROWSERS_PATH points the driver at an already-populated Chromium cache instead of downloading a fresh one.

Legacy mirror, not used by default: clickprobe-proxy install --mirror-chromium additionally downloads a second, separate Chromium copy from https://playwright.azureedge.net (falling back automatically to https://clickprobe.ai/downloads/chromium/ if that CDN is unreachable) into the proxy’s own data directory. This is not the browser the product launches — it exists only for a legacy status-mirror use case and is off by default since clickprobe-proxy 0.1.2-beta. Most users never need this flag — it exists for continuity with an older status-check mechanism, not for anything the exploring browser itself uses.

”The dashboard shows Offline”

The local WebUI dashboard (clickprobe-proxy webui, http://127.0.0.1:9100) reports one of three states, and each points at a different layer:

Status shownMeaningWhere to look
Not logged inThe proxy has no valid auth token.Run clickprobe-proxy and complete the OAuth flow again (Onboarding Guide → Step 4).
Tunnel down: <sentence>You’re authenticated, but the WebSocket to broker.clickprobe.ai isn’t currently connected — the dashboard and clickprobe-proxy status now name which layer failed (PLAN-280).If it says the hostname could not be resolved, that is a condition on ClickProbe’s side, not your network — the corporate-proxy/TLS sections below won’t help; check status.clickprobe.ai or try again later. If it says the connection timed out or the TLS certificate could not be verified, that is the genuine corporate-proxy/TLS-interception case — see the sections above. If it says the connection was refused or rejected at the HTTP layer, restart the proxy process and check your machine’s own internet connection.
OnlineAuthenticated and tunnel connected.If the cloud dashboard (app.clickprobe.ai → Machines) still shows the proxy as offline while the local WebUI says Online, wait a few seconds for the next heartbeat — if it persists, restart the proxy.

If none of the above resolves it, the local dashboard’s Diagnostics → Download bundle produces clickprobe-diag.zip — the last 1000 log lines, a redacted config (the WebUI token is stripped), current state, and version info. Email it to beta@clickprobe.ai and we can usually tell what’s wrong from the logs alone.

Outbound hosts your network needs to allow

For reference, everything clickprobe-proxy talks to outbound. All plain HTTPS/WSS on port 443 — nothing else is required, and no inbound port needs to be opened.

HostPurpose
broker.clickprobe.aiThe persistent WebSocket tunnel — instructions in, screenshots/results out. This is still the correct hostname to allowlist, even if a lookup against it fails today; if your proxy reports dns_no_such_host, that is a condition on ClickProbe’s side (see the dashboard-status table above), not a sign your allowlist entry is wrong.
api.clickprobe.aiREST API — auth, session metadata.
app.clickprobe.aiOnly needed if you use the OAuth/login flow from the same restricted network; the proxy itself doesn’t call this host directly.
registry.npmjs.orgOne-time driver download (the playwright-core npm package).
nodejs.org (nodejs.org/dist)One-time Node.js runtime download the driver runs on.
cdn.playwright.devOne-time Chromium download — the browser clickprobe-proxy actually launches.
playwright.azureedge.net and clickprobe.ai/downloads/chromium/Only needed if you pass --mirror-chromium (legacy, off by default — see above).
clickprobe.ai/downloads/latest/VERSIONVersion-staleness check: a plain, unauthenticated GET on every clickprobe-proxy status and once at daemon startup, comparing the published version to yours. Carries no account id, token, machine label, or session id — the request can’t be linked to you. Silent and non-blocking if unreachable. Disable with CLICKPROBE_DISABLE_UPDATE_CHECK=1.

If you’re pre-approving destinations in a change request rather than debugging a live failure, this table is the complete list — nothing else needs an exception.