Wallfacer
On this page

The Agent's Browser

Published

Updated

Wallfacer opens a headless Chromium in the agent's VM when it needs to browse. The agent opens a page, reads what is on it, clicks and types, and captures what it sees. In-page navigation and sign-ins carry between steps. For an agent, saved sign-ins can also carry into a later session or a new sandbox.

This is the agent's own browser. It is not the Web Preview panel, which is the embedded view you use to look at a service running in the VM.

What It Can Open

Two kinds of target:

  • Any page on the open web, given a URL. https://trello.com/signup and trello.com/signup both work; a bare host is read as https.
  • A service of the agent's own environment, named as it appears in the manifest, with an optional path. The agent names the service rather than a port, and the transcript records which service it opened.

A sandbox-local address passed as a URL is refused, and the refusal points at the service form instead. That covers localhost, private and link-local IP ranges including the cloud metadata endpoint, and the .local and .internal suffixes. The refusal is about naming: the environment's own services are reachable, through the argument that says so.

Browsing grants the agent no network access it did not already have. A session's shell has outbound network, so the browser is a way to see and drive a page, not a new door out of the VM.

Availability

Every Linux session has it, whether or not the environment declares a web service. Nothing in the manifest turns it on, and an environment that serves no pages of its own can still browse the web.

macOS environments do not have it. The Chromium-backed tools ship in the Linux sandbox image only, so a session on a macOS environment is told it has no browser and is pointed at the iOS Simulator to see a running app instead.

Signing In Without Exposing the Password

When a page asks for a credential the agent holds on the account keychain, the agent fills the field by naming the credential. The value goes from the VM into the form without passing through the model or the session transcript. Time-based codes work the same way: one is minted at the moment the field needs it.

Granting the credential is the whole setup. An agent that names a credential it was not granted is refused.

Saved Browser Sign-ins

An agent's browser saves cookies, local storage, and IndexedDB after browser actions. It restores that state the next time the same agent opens a browser, even after an idle shutdown, a new session, or a new sandbox. The saved state belongs to that agent. A browser session without an acting agent starts without saved sign-ins.

Only one session for an agent can use and update its saved sign-ins at a time. If another session browses at the same time, that browser starts signed out and does not save its state. If a saved state cannot be restored, the browser starts signed out and the agent's Browser settings report the problem. A site may still ask the agent to sign in again when its own session expires.

To see whether anything is saved or clear it, open the agent's Configure tab on the dashboard and find Browser. Any account member can view the status and last saved time. An admin or owner can choose Clear browser state. Clearing deletes the saved sign-ins and stops a browser currently using them. The agent's next browser starts signed out. Offboarding an agent also clears its saved browser state.

The status endpoint is GET /v1/accounts/{account_id}/agents/{agent_user_id}/browser-state. Admins can clear it with DELETE on the same path. See the API Reference for response fields and the pending-clear response.

Solving CAPTCHA Challenges

When a page presents a supported challenge, the agent can use browser_solve_captcha to solve reCAPTCHA v2, Arkose Labs FunCaptcha, or Cloudflare Turnstile, including Turnstile on a Cloudflare challenge page. The tool reports whether it solved the challenge, failed, timed out, or found an unsupported type. After a successful solve, the agent may still need to submit the page's form.

The solver has limits on attempts, time, and account spending. It cannot solve every challenge: hCaptcha, reCAPTCHA v3 and Enterprise, image CAPTCHAs, and challenges that require the solver to share the browser's IP are unsupported. A page can also reject a returned answer. The agent sees the outcome and can decide whether to retry or ask you to complete the step.

What You See

Each capture the agent takes carries a permanent shareable URL. Agents embed those in pull request test plans to show a reviewer the page they verified, and paste them into chat when you ask what something looks like. Captures from a browsing session and single-shot service renders both appear this way.

The steps in between are in the session transcript: the page opened, the element acted on, the result read back.

Related