diff --git a/browsers/live-view.mdx b/browsers/live-view.mdx index 90e6503d..7cfefa9a 100644 --- a/browsers/live-view.mdx +++ b/browsers/live-view.mdx @@ -64,6 +64,8 @@ https://api.onkernel.com/browser/live/?readOnly=true The live view URL can be embedded in an iframe to integrate the browser view into your own application or dashboard. +If your environment restricts outbound traffic, allow the [Live View domains and ports](/info/network-access#required-destinations) before you embed it. + ```html ``` @@ -74,7 +76,7 @@ The live view URL can be embedded in an iframe to integrate the browser view int To enable clipboard sharing, add `allow="autoplay; clipboard-read; clipboard-write"` to the iframe element. -Kernel serves live views from `*.onkernel.com:8443` and `*.kernel.sh:8443`. If your application uses a **Content Security Policy (CSP)**, you must add the following directives to allow the live view iframe and its WebSocket connection: +If your application uses a **Content Security Policy (CSP)**, you must add the following directives to allow the live view iframe and its WebSocket connection. See [Network access](/info/network-access#content-security-policy) for the complete firewall and CSP requirements. ``` frame-src https://*.onkernel.com:8443 diff --git a/browsers/replays.mdx b/browsers/replays.mdx index 1e341f27..a0ffefb3 100644 --- a/browsers/replays.mdx +++ b/browsers/replays.mdx @@ -242,6 +242,8 @@ func main() { Set an iframe's `src` to the `replay_view_url` returned when you start or list a replay. Give the iframe an explicit aspect ratio so the player keeps its shape while loading, and enable fullscreen playback. Merge the example's `frame-src` sources into your existing Content Security Policy. +If your environment restricts outbound traffic, allow the [replay domains and ports](/info/network-access#required-destinations) before you embed the player. + Replace `REPLAY_VIEW_URL` with the URL returned by the API: ```html diff --git a/docs.json b/docs.json index 146a7218..38c1cf4f 100644 --- a/docs.json +++ b/docs.json @@ -291,6 +291,7 @@ { "group": "Info", "pages": [ + "info/network-access", "browsers/faq", "info/concepts", "info/zero-data-retention", diff --git a/info/network-access.mdx b/info/network-access.mdx new file mode 100644 index 00000000..64fe89cf --- /dev/null +++ b/info/network-access.mdx @@ -0,0 +1,58 @@ +--- +title: "Network Access" +description: "Domain and port allowlist for connecting to Kernel" +--- + +Add these destinations to your allowlist when a firewall, proxy, or sandbox restricts outbound traffic. You don't need to open inbound ports. + +Allow only the destinations used by your integration. Apply the Live View and replay rules to each viewer's network, not just the machine running your agent. + +## Required destinations + +| Feature | Destinations | Port | Protocol | +| --- | --- | --- | --- | +| API, SDKs, and authenticated CLI requests | `api.onkernel.com` | `443` | HTTPS | +| CLI authentication (`kernel login`) | `auth.onkernel.com`, `dashboard.onkernel.com` | `443` | HTTPS | +| CDP, WebDriver BiDi, Live View, replays, and app connections | `*.onkernel.com`, `*.kernel.sh` | `8443` | HTTPS and secure WebSocket (WSS) | +| Live View media negotiation | `stun.relay.metered.ca` | `80` | STUN over UDP | +| Live View media relay | `global.relay.metered.ca` | `443` | TURN over UDP or TLS/TCP | +| Replay files | `kernel-api-prod.s3.us-east-1.amazonaws.com` | `443` | HTTPS | + + + Allow both wildcard domains. Don't copy a single hostname from a returned `cdp_ws_url`, `webdriver_ws_url`, or `browser_live_view_url`, because that hostname can change between sessions. + + +## Content security policy + +A network allowlist permits traffic leaving your environment. A Content Security Policy (CSP) permits content loaded by your web application. If you embed Live View or replays, configure both. + +### Live View + +Merge these sources into your application's existing CSP: + +```text +frame-src https://*.onkernel.com:8443 + https://*.kernel.sh:8443; +connect-src https://*.onkernel.com:8443 + wss://*.onkernel.com:8443 + https://*.kernel.sh:8443 + wss://*.kernel.sh:8443; +``` + +### Replays + +Merge these sources into your application's existing `frame-src` directive: + +```text +frame-src https://*.onkernel.com:8443 + https://*.kernel.sh:8443 + https://kernel-api-prod.s3.us-east-1.amazonaws.com; +``` + +## Troubleshooting blocked connections + +- If API, SDK, or authenticated CLI requests time out, verify access to `api.onkernel.com:443`. +- If `kernel login` doesn't complete, verify access to `auth.onkernel.com:443` and `dashboard.onkernel.com:443`. +- If browser creation succeeds but CDP, WebDriver BiDi, or Live View won't connect, verify access to both wildcard domains on port `8443`. +- If Live View loads but remains disconnected or doesn't show video, verify access to the STUN and TURN destinations. +- If the replay player loads but a recording doesn't play, verify access to the replay file destination. diff --git a/integrations/claude/claude-managed-agents.mdx b/integrations/claude/claude-managed-agents.mdx index e1e78a89..c8f11062 100644 --- a/integrations/claude/claude-managed-agents.mdx +++ b/integrations/claude/claude-managed-agents.mdx @@ -85,6 +85,8 @@ const env = await client.beta.environments.create({ }, }); ``` + +This allowlist lets the worker call the Kernel API. If you adapt the worker to connect directly over CDP or WebDriver BiDi, also allow the [browser connection domains and ports](/info/network-access#required-destinations). diff --git a/introduction/control.mdx b/introduction/control.mdx index 06abc092..5ec902ce 100644 --- a/introduction/control.mdx +++ b/introduction/control.mdx @@ -291,3 +291,4 @@ fmt.Println(response.Result) - [Computer Controls reference](/browsers/computer-controls) — every mouse, keyboard, and screen primitive. - [Playwright Execution reference](/browsers/playwright-execution) — the full execution surface, return values, and timeouts. - [Computer use integrations](/integrations/computer-use/anthropic) — drop-in examples for Anthropic, Gemini, OpenAI, and more. +- [Network access](/info/network-access) lists the domains and ports to allow for API, CDP, and WebDriver BiDi connections. diff --git a/introduction/create.mdx b/introduction/create.mdx index bc9f8aaf..11700c97 100644 --- a/introduction/create.mdx +++ b/introduction/create.mdx @@ -66,6 +66,8 @@ kernel browsers create --stealth --start-url https://example.com The response includes everything you need to drive the browser: `session_id`, `cdp_ws_url`, `webdriver_ws_url`, and `browser_live_view_url`. +If your environment restricts outbound traffic, add Kernel's [domains and ports](/info/network-access) to its allowlist. + ## Pick the right shape Most of what you'll tune at creation time falls into four buckets: diff --git a/introduction/observe.mdx b/introduction/observe.mdx index 1ae528ff..167e470f 100644 --- a/introduction/observe.mdx +++ b/introduction/observe.mdx @@ -58,6 +58,8 @@ kernel browsers view Add `?readOnly=true` for a non-interactive view, or enable [kiosk mode](/browsers/live-view#kiosk-mode) at creation for a fullscreen, cinematic experience. Full reference: [Live View](/browsers/live-view). +If a firewall or network policy restricts outbound traffic, allow the [Live View domains and ports](/info/network-access#required-destinations). + ## Replays Replays are MP4 recordings you start and stop on demand - capture as many clips per session as you need. They're the right tool for post-hoc debugging: a failed run gives you one or more videos to scrub through, share, or attach to a bug report.