OpenClaw Hosted Browser Sidecar: secure cloud access for browser-heavy agents

Browser automation is where a personal AI assistant moves from conversation to operational work. It can open a dashboard, inspect a broken page, gather screenshots, compare a deployment, or work through a logged-in admin flow. The hard part is not launching Chromium once. The hard part is keeping browser state persistent, private, reachable by the agent, visible to the owner, and isolated enough that one bad tab does not take down the whole OpenClaw runtime.

OpenClaw Setup now handles that with a hosted browser sidecar for managed instances. Each enabled instance gets a persistent browser profile, a pod-local Chrome DevTools Protocol endpoint for OpenClaw tools, and a dashboard-accessible KasmVNC viewer behind the same authenticated backend proxy pattern used by other managed add-ons.

This article explains the design, the failure modes it avoids, how to verify it, and when you should use Hosted Browser instead of connecting your own Chrome through the Chrome Extension relay. For the product overview, start with OpenClaw with browser or the Hosted Browser feature page.

The problem: browser access has two different users

A hosted OpenClaw browser has two users: the agent and the human owner. The agent needs a programmable browser endpoint. The owner needs to see and control the browser when credentials, captchas, account state, or visual debugging require human judgment. Those are different interfaces with different risk profiles.

Raw CDP is excellent for an agent. It is also a powerful control surface. Exposing it to the public internet would be a serious mistake. A visual desktop stream is useful for the owner, but it also carries cookies, local storage, active sessions, and whatever pages are open. Treating either surface as a normal public web app would make the browser the weakest link in the deployment.

The safer pattern is to keep the agent control plane inside the pod and expose the human viewer only through an authenticated product path. That is the core of the sidecar design.

Evidence from the field

The implementation was not designed from a whiteboard alone. The immediate product evidence came from a shipped hosted-browser branch and production follow-up:

• The browser sidecar uses the existing instance persistent volume and stores profile state under /home/node/.openclaw/hosted-browser/profile, so cookies and tabs can survive pod restarts without copying a user's local Chrome data.
• OpenClaw config points the hosted browser profile at http://127.0.0.1:9222 with attachOnly, keeping the agent contract aligned with OpenClaw's browser tooling instead of inventing a second API.
• Local container smoke caught two practical restart bugs before production: Chromium needed the display environment, and stale singleton locks had to be removed so a persistent profile volume could recover cleanly.
• The first viewer stack worked, but the noVNC experience was not good enough for everyday browser work. The viewer was replaced with KasmVNC, which reduced moving parts and improved clipboard-oriented workflows.
• A production TLS check found a real certificate gap for *.browser.openclaw-setup.me. Adding a dedicated browser ingress and wildcard certificate fixed the default Traefik certificate response and made the browser URL validate over HTTPS.

Those details matter because browser hosting often fails through ordinary runtime faults: stale profiles, broken display processes, bad proxy WebSocket handling, default certificates, and dashboard state that says one thing while the pod is already healthy. A reliable hosted browser design has to account for those edges, not just install Chromium.

The architecture in plain English

Each managed OpenClaw instance already has a Kubernetes deployment and persistent storage. When Hosted Browser is enabled, OpenClaw Setup adds a browser sidecar container to the same pod. The OpenClaw gateway container and browser container share the pod network namespace, so the gateway can reach the browser's CDP endpoint over loopback.

The browser sidecar starts KasmVNC's Xvnc display, Fluxbox, and Chromium. Chromium uses the persistent profile path on the instance volume and exposes remote debugging on 127.0.0.1:9222. The visual browser viewer runs on a separate sidecar port, but users do not open that port directly. The dashboard asks the backend for a browser launch session, and the backend proxies HTTP and WebSocket traffic after authenticating the owner.

In practical terms: the agent gets an attachable browser profile, and the user gets an authenticated browser tab in the dashboard. The risky raw control surfaces stay behind pod and backend boundaries.

Why not use the local Chrome relay for everything?

The Chrome Extension relay solves a different job. It connects OpenClaw to tabs in your own Chrome profile. That is the right answer when the workflow depends on your local browser, local device, or already-open session. It is not the right default when a managed instance needs an always-on browser that belongs to the hosted runtime.

A hosted browser profile should be scoped to the hosted instance. It should not require your laptop to stay online. It should not need cookie copying from a personal profile. It should survive runtime restarts. It should be resettable when a profile gets into a bad state. Those requirements point to a managed browser sidecar, not a relay into a human desktop session.

Diagnostics: how to tell if the hosted browser is healthy

If a browser-heavy OpenClaw task fails, do not immediately assume the model or website is at fault. Check the browser layer in order:

1. Confirm the addon is enabled. In the instance Addons tab, Hosted Browser should be enabled and saved. If it was just enabled, give the runtime a moment to roll the pod.
2. Check runtime status. The instance should be running, and the pod should show both containers healthy. A one-container pod means the sidecar is not active yet.
3. Open the browser from the dashboard. If the viewer opens, the authenticated proxy path, TLS, and KasmVNC web client are at least reachable.
4. Verify agent control separately. The viewer can work while CDP is unavailable, and CDP can work while the viewer has a proxy problem. For agent tasks, the key path is pod-local CDP.
5. Check profile recovery. If Chromium refuses to start after a restart, stale singleton locks or corrupted profile state are more likely than a bad website.
6. Reset only when needed. A browser profile reset can clear corrupted state, but it can also remove useful logged-in sessions. Try restart before reset unless the profile is clearly broken.

Common mistakes

• Opening CDP directly. CDP is for the OpenClaw runtime inside the pod, not for public browser access.
• Copying a personal Chrome profile into production. That can move sensitive state into a shared operational environment and create hard-to-debug profile locks.
• Assuming the viewer is the agent path. The visual browser helps the owner. The agent uses browser tooling through CDP.
• Skipping TLS verification. A browser subdomain that serves a default certificate is not ready for real account sessions.
• Using hosted browser for every local tab workflow. If the task requires your current desktop Chrome state, use the relay instead.

Step-by-step: choosing the right browser path

1. Use Hosted Browser when the browser should run next to the hosted agent, stay online, and keep its own managed profile.
2. Use Chrome Extension relay when the agent must interact with tabs in your real local Chrome profile.
3. Use plain web fetch tools when the page does not need login state, visual inspection, JavaScript interaction, or screenshots.
4. Use manual dashboard access when a human needs to sign in, approve a session, inspect visual state, or recover a stuck browser.

The cleanest production pattern is not one browser path for every job. It is a deliberate split: managed cloud browser for hosted workflows, relay for personal Chrome workflows, and simple fetch for plain public pages.

Verification checklist before trusting it with production work

• The instance status is running after enabling Hosted Browser.
• The dashboard browser opens over HTTPS without certificate warnings.
• The browser profile persists across a restart.
• A simple OpenClaw browser task can open a page and report visible page state.
• The visual viewer and agent-controlled browser refer to the same profile state.
• Reset profile is documented as a destructive recovery action for browser state, not a routine restart step.

Where this fits in the hosting decision

Browser automation is one of the clearest lines between a hobby OpenClaw instance and a production assistant. If the browser only runs when your laptop is awake, scheduled work is fragile. If browser access depends on public VNC, raw CDP, or copied cookies, the security model is weak. If no one owns browser restarts, profile recovery, TLS, and proxy behavior, the agent will fail exactly when the task becomes valuable.

That is why Hosted Browser belongs in the managed hosting layer. It is not just a convenience button. It is runtime infrastructure for agents that need durable, inspectable web access.

FAQ

Does Hosted Browser replace Chrome Extension relay?

No. Hosted Browser and Chrome Extension relay solve different workflows. Hosted Browser is for a managed cloud browser profile attached to the instance. Chrome Extension relay is for controlled access to your local Chrome tabs.

Can I use Hosted Browser for logged-in dashboards?

Yes, that is one of the main use cases. The important rule is to treat the hosted browser profile as credential-bearing state. Keep access owner-authenticated, avoid public control endpoints, and reset the profile only when you are willing to lose those sessions.

What happens if the browser crashes?

The sidecar design keeps the browser process separate from the OpenClaw gateway process. A restart can recover the browser container or pod without making browser lifecycle inseparable from the agent runtime. Persistent profile state stays on the instance volume unless you reset it.

How is this different from a screenshot-only browser tool?

Screenshot-only tools are useful for observation, but many real workflows need interaction, login, clipboard behavior, and human recovery. KasmVNC gives the owner a visual browser surface while OpenClaw tools still attach through CDP for agent control.

What should I compare before moving a self-hosted browser workflow?

Compare uptime expectations, credential boundaries, profile persistence, recovery controls, TLS, and who owns browser maintenance. The OpenClaw hosting comparison is the best next page if you are deciding whether to keep browser automation self-hosted or move it into a managed instance.