Skip to main content
Use the built-in web browser to inspect a web app from an Ona environment. When Ona AI is enabled, you can also share page state with Ona and send screenshots from the Browser tab into the conversation. The browser runs inside the environment, so it can access services on that environment’s local ports.
The built-in web browser is enabled by default for all organization tiers. Enterprise admins can disable it with the web browser organization policy.
Browser tab open next to an Ona conversation in a running environment

​
Where the browser is available

The built-in browser appears on environment pages when all of these are true:
  • The environment is in a phase where actions can be opened, such as a running environment.
  • The organization allows the built-in browser.
  • The environment supervisor supports the browser controller.
When available, the dashboard shows Open Browser, Preview … in Browser, or the Browser tab. If the browser is not available, port previews fall back to external shared-port links. The Annotate browser and Send screenshot to Ona actions appear only when Ona AI is enabled for the organization.

​
Enable or disable the browser

The browser is enabled by default for Free, Core, and Enterprise organizations. Enterprise admins can disable or re-enable it from Settings > Organization > Policies > Allow Web Browser in Environments. Disabling the policy has these effects:
  • The dashboard hides browser actions and the Browser tab.
  • Ona does not expose the browse-web built-in skill to agents in that organization.
  • Members cannot start the environment’s managed browser session from the dashboard.
Disabling the policy does not disable port sharing, VS Code Browser, or editor access. Those features have separate controls.

​
Security and ports

The built-in browser is separate from shared port URLs. Opening a local app in the Browser tab does not make that app public. For port previews, Ona navigates the managed browser to an environment-local address, such as http://localhost:3000. Port sharing is still relevant for the browser’s own connection. When the browser starts, Ona declares a managed browser port so the dashboard can connect to the browser session. That managed port is for the Browser tab and is not the same as sharing your app’s port with other people. Use port sharing when you need a URL outside Ona, such as a teammate preview link or a webhook callback URL. Use the built-in browser when you want a preview inside Ona that you and Ona can both inspect.

​
Open the browser manually in the product

Open the browser from an environment details page:
  1. Open a running environment.
  2. Select Open Browser to open a blank Browser tab.
  3. To preview a local app, select Preview … in Browser from a listed port.
If the browser is not already running, Ona starts it for the environment and opens the Browser tab. Open Browser button on a running environment page You can also use the Browser tab directly:
  • Type a URL in the browser address field.
  • Use back, forward, reload, and external-open controls from the Browser tab header.
  • Switch between desktop and mobile viewport mode.
  • Close the Browser tab without stopping the environment.
Browser tab switched to mobile viewport mode

​
Ask Ona to use the browser

When Ona AI is enabled, ask Ona to use the browser when a task requires visual inspection, page interaction, screenshots, videos, console output, or network requests. Mention the URL or port and the behavior you want checked. Examples:
  • Open the browser and verify the app on port 3000 loads without console errors.
  • Use the browser to reproduce the login bug on localhost:8080 and tell me which step fails.
  • Open the settings page in the browser, take a screenshot, and explain why Save is disabled.
  • Record a short video of the onboarding flow in the browser and attach it to the conversation.
If your app is not already running, include that in the prompt: 
Start the frontend, open it in the browser on port 5173, and check whether the checkout modal still overflows on mobile.
The Browser tab and Ona use the same browser session for the environment. If you navigate, sign in, or change page state manually, Ona can continue from that state. If Ona navigates or fills a form, you can watch the change in the Browser tab.

​
Send screenshots and annotations to Ona

When Ona AI is enabled, use screenshots when Ona needs to inspect the exact page state you are seeing.
  • Send screenshot to Ona captures the current Browser tab and opens a message prompt with the screenshot attached.
  • Annotate browser lets you draw on the page, describe what to change, and send the annotated screenshot to Ona.
  • Mobile viewport switches the Browser tab between desktop and mobile viewport modes before you capture or annotate.
Prompt for sending a Browser tab screenshot to Ona Use annotations for precise UI feedback, such as pointing at an overflowing element, a missing label, or a disabled button. Use a plain screenshot when the whole page state is enough. Browser annotation draft with a circled area and a message prompt After you send the annotation, Ona receives the marked-up screenshot in the conversation and can respond to the highlighted page state. Annotated Browser screenshot attached to an Ona conversation You can also ask Ona to capture artifacts while it uses the browser:
  • Use the browser to open the dashboard on port 3000 and attach a screenshot of the billing page.
  • Record a short video of the signup flow in the browser and tell me where the error appears.
  • Take screenshots before and after submitting the form so I can compare the UI states.

​
FAQ

No. Opening a port in the built-in browser keeps the preview inside the environment page. Use Port sharing when you need a URL that can be opened outside the environment page.
Yes. The Browser tab and Ona share the same browser session for the environment, so Ona can continue from the state that is already open.
No. Port sharing and the built-in browser use separate policies. The built-in browser is controlled by the web browser policy.
Yes, when Ona AI is enabled. Ona and the Browser tab use the same browser session for the environment. If you sign in, navigate, or change page state in the Browser tab, Ona can continue from that state when you ask it to use the browser.

​
Troubleshooting

The environment may not be running, the environment supervisor may not support the browser yet, or your Enterprise organization may have disabled the web browser policy. Ask an organization administrator to check Settings > Organization > Policies > Allow Web Browser in Environments.
The environment may be running on a supervisor version that does not support the built-in browser. Restart the environment after the runner is upgraded, then try opening the browser again.
Check that the app is running and listening on the expected port. If the app also needs to be reachable through Ona port handling, follow the bind-address and network guidance in Port sharing.