Browser Use
Use Browser Use to let CloudCLI agents inspect real web pages, verify UI behavior, and hand control to you when a login or approval step is needed.
Browser Use
Browser Use lets CloudCLI agents open and use a real browser while they work. Instead of relying only on source code or server responses, an agent can inspect the rendered page and tell you what is actually happening in the UI.
Use Browser Use when a task depends on what a user would see: reproducing a frontend bug, checking a staging page, verifying a visual fix, or pausing while you complete a login or MFA step.
Browser Use is opt-in. When it is disabled, agents cannot create browser sessions and the Browser panel stays hidden.
What Browser Use Does
Browser Use gives an agent eyes and hands in a browser. The agent can load a site, interact with the page, and report what is visible, broken, or changed.
This is useful when the answer depends on the rendered product: a button that does not respond, a layout that shifts at runtime, a staging page that needs visual review, or an authenticated workflow that cannot be checked from source code alone.
From the Browser panel, you can follow the session in CloudCLI. If the session supports a visible browser, you can take control for login, MFA, or any other human-only step, then let the agent continue from the same browser state.
How It Works
After you enable Browser Use, CloudCLI adds browser access to your configured agents through the cloudcli-browser MCP server. When an agent needs a browser, CloudCLI starts a browser session and keeps track of its current page, screenshot, status, and session state.
The agent controls the browser through structured actions such as opening pages, clicking, typing, waiting, and reading page state. You do not create sessions manually from the Browser panel; agents create them when the task requires a browser.
If the selected browser backend supports a live viewer, CloudCLI also creates a protected viewer link. That lets you open the same browser session, complete a human step, and return control to the agent.
For the surrounding implementation, see Architecture Overview and the Network Architecture Guide.
Browser Engines
CloudCLI supports two browser backends. Choose the one that matches the type of work you expect agents to do.
Playwright
Use Playwright for automated checks where the agent only needs to inspect or interact with the page. It is the default for local and self-hosted environments.
Playwright is a good fit for public pages, deterministic frontend flows, screenshots, and quick visual checks. It does not provide a live noVNC viewer for manual takeover.
Camoufox + noVNC
Use Camoufox + noVNC when a person may need to watch or take over the browser. It is the default backend for hosted CloudCLI environments.
This backend is useful for login-gated apps, MFA, approval prompts, and workflows where the agent should continue after a human completes a step. When available, the Browser panel shows Take control for the session.
Turn Browser Use On
- Open Settings.
- Select Browser.
- Turn on Give Agents Browser Access.
- Choose a browser engine.
- Optional: turn on Remember Browser Logins.
- Install missing runtime dependencies if CloudCLI prompts you to do so.
The settings page also shows whether the required browser runtime is available on the machine running CloudCLI.
Saved Logins And Profiles
Turn on Remember Browser Logins when agents should reuse cookies and local storage across browser sessions. This is useful for authenticated dashboards, staging apps, and internal tools that you expect agents to revisit.
When profile persistence is off, sessions start from a temporary clean browser context. When it is on, sessions use the configured profile name, which starts as default. Persistent profiles are stored under ~/.cloudcli/browser-use/profiles.
Use persistent profiles deliberately. They make repeated authenticated work easier, but they also keep browser state between sessions.
Session Lifetime
A browser session is a live browser process, not a permanent saved browser. It stays active while the runtime is alive and expires after inactivity. Stopping or deleting a session closes the live browser runtime.
Restarting CloudCLI ends active browser sessions. If profile persistence is enabled, saved cookies and local storage can still be reused by future sessions that use the same profile.
Common Workflows
Reproduce a UI bug
Ask the agent to open the page, reproduce the issue, and report what it sees. Browser Use is most helpful when the bug depends on rendered state, client-side behavior, or a real page flow.
Verify a frontend fix
After an agent changes frontend code, ask it to reopen the relevant page and confirm the behavior visually. This catches issues that unit tests or code inspection may miss.
Complete a login handoff
Use the visible browser backend when the agent reaches a login, MFA, or approval screen. Open the Browser panel, choose Take control, complete the human step, and let the agent continue from the same session.
Reuse authenticated state
Enable Remember Browser Logins when future sessions should start from the same signed-in browser profile.
Runtime Requirements
Browser Use depends on the selected backend being installed where CloudCLI runs.
Playwright requires Playwright and Chromium. Camoufox + noVNC requires the visible-browser runtime, including Camoufox, noVNC, x11vnc, and display support.
CloudCLI can install some Playwright and Chromium dependencies from the Browser settings page. Self-hosted visible-browser setups may require system packages on the host machine.
For cloud environment setup more generally, see What is CloudCLI Cloud? and Running and Previewing Your App.
Safety Notes
Browser Use gives agents access to a real browser session, so enable it only when you want agents to use browser automation.
Prefer temporary sessions when you do not want cookies or logins kept. Use persistent profiles only for accounts you are comfortable reusing. Stop sessions that no longer need to stay active, especially when they can access private dashboards, billing systems, or sensitive user data.
Troubleshooting
Open the item that matches what you see, then follow the checks in order.
Browser Use is unavailable
Confirm Give Agents Browser Access is enabled in Settings -> Browser. Then check the runtime status on the same page. If CloudCLI reports missing dependencies, install them and restart CloudCLI if required.
The Browser panel is empty
No agent has created a browser session yet, or Browser Use is disabled. Enable Browser Use, then ask an agent to inspect a page, reproduce a flow, or verify a frontend change.
Take control is missing
The session is probably using the Playwright backend. Playwright supports automated browser work and screenshots, but not live noVNC takeover. Switch to Camoufox + noVNC when you need visible browser control.
The visible viewer does not connect
Confirm the session was created with the visible backend, then open the newest viewer link from the Browser panel. In self-hosted environments, verify that Camoufox, noVNC, x11vnc, and display support are installed on the host.
Sessions keep asking for login
Turn on Remember Browser Logins, keep the same profile name, and sign in once through a persistent-profile session. Future sessions that use that profile can reuse the saved browser state.