# Secure Browser The secure browser is a remote AWS Bedrock AgentCore browser that a Topline operator can control without exposing a local browser profile to a chat or coding agent. Use it for authenticated web workflows, human sign-in, and approved browser assistance attached to a Topline chat or coding task. The secure browser is not a new Chrome window on the operator's computer. The page shown in Topline is a control surface for an isolated cloud browser. ## Who can use it The secure-browser button and API require all of the following: - an authenticated Topline browser session; - a tenant identity; - the `harness.browser` capability; and - a configured AgentCore browser identifier in the server environment. The monitor button in a chat header is hidden when the current user does not have `harness.browser`. The server repeats the same authorization check on every browser API request; hiding the button is not the security boundary. ## Open a browser from chat 1. Open a chat. 2. Select **Open secure browser** in the chat header. 3. Topline opens `/browser?conversation=` in a new tab. 4. Select an existing browser profile or create one. 5. Optionally enter a complete `http` or `https` starting URL. 6. Select **Open browser**. Topline verifies that the conversation belongs to the signed-in operator and tenant. If the conversation has an active coding task, the browser session is attached to both the conversation and that task. The browser URL then changes to `/browser?session=`. Opening `/browser` directly starts the same workflow without attaching the session to a chat. ## Browser profiles A browser profile is a reusable AgentCore browser identity owned by one Topline user inside one tenant. The Topline database stores the user-facing profile record and the provider profile identifier; the web client receives only the Topline profile ID and whether an AgentCore profile exists. Profile names may contain letters, numbers, underscores, and hyphens and must be 1-48 characters. Names are unique per operator and tenant. ### Save sign-in After signing in through the remote browser, select **Save sign-in** to ask AgentCore to save the current session state into the selected profile. Topline uses a five-minute profile lease while saving so two sessions cannot overwrite the same profile at the same time. A conflicting save returns `browser_profile_busy`; wait for the other save to finish or expire and retry. Saving a profile is always a human action. Coding agents cannot save browser profiles. ## Remote browser controls AgentCore starts each browser with a 1440 x 900 viewport and a one-hour session timeout. The Topline page provides these controls: - **Browser view** - a PNG screenshot of the remote page; - **Click** - select a point in the screenshot to click the corresponding remote coordinate; - **Refresh** - request a new screenshot immediately; - **Type** - send text to the field currently focused in the remote browser; - **Enter**, **Tab**, **Shift + Tab**, and **Escape** - send common navigation keys; and - **End session** - stop the AgentCore session after confirmation. The browser view is screenshot-based, not a video stream. Topline requests a new screenshot when the page opens, after a human action, and every eight seconds while the session is active. A screenshot request already in progress is not duplicated. Click coordinates are scaled from the displayed image back to the fixed remote viewport. If a page changes between the screenshot and the click, refresh the view and try again. ## Chat and coding-task integration While a browser session is active, the chat shows a browser card with its profile name and whether it is attached to the chat or coding task. The card checks for an active session every 15 seconds and provides **Open** and confirmed **End session** actions. Only one owner-scoped, task-attached active session can be used for a brokered coding-agent action. No matching session produces `browser_session_not_attached`; multiple matching sessions produce `browser_session_ambiguous`. ## Agent-proposed browser actions When `BROKERED_BROWSER_APPROVALS_ENABLED=true`, a coding agent may propose one bounded action against the browser explicitly attached to its task: - click a coordinate; - press Enter or Tab; or - type up to 1,000 characters into a verified non-sensitive field. Each proposal: 1. is bound to the tenant, operator, conversation or task, and browser session; 2. captures bounded evidence such as the current screenshot, URL, title, and active-field metadata; 3. creates a pending approval that expires after five minutes; 4. requires explicit operator confirmation; 5. hashes the exact action so an approved action cannot be replaced before execution; and 6. records proposal and execution outcomes in the browser and audit history. Rejected, expired, mismatched, inactive-session, and provider-failed actions do not execute. ### Actions that always require the human Agents must not enter or handle: - passwords or passcodes; - one-time codes, MFA, or authenticator values; - payment-card or payment fields; - CAPTCHAs; - account-recovery values; - destructive actions; or - browser-profile saving. Agent typing is rejected unless the proposal declares a non-sensitive purpose and AgentCore inspection confirms that the focused field does not appear sensitive. Text that resembles credentials, verification codes, or authenticator values is also rejected. ## Security and data boundaries - Browser profiles, sessions, and approvals are scoped by tenant and owner. - The API accepts session authentication only; bearer-only callers cannot use the human browser interface. - AWS provider session IDs and profile IDs are not returned to the web client. - Starting URLs must use `http` or `https`. - Direct human click, type, key, and screenshot requests are sent from the secure-browser page to the Topline server and then to AgentCore. Typed values are not inserted into chat messages or browser approval records. - Support and audit workflows must not request provider session IDs, cookies, typed values, or raw browser-page content. - Approval evidence is retained for 30 days by the scheduled cleanup policy; minimal audit records remain after evidence cleanup. "Credentials never enter chat" means operators enter credentials through the dedicated browser control surface instead of sending them as chat messages. It does not mean the remote browser can authenticate without processing the value through the Topline server and AgentCore action path. ## Session lifecycle New sessions are stored as active with a one-hour expiration. Successful actions update the session's last-activity timestamp. Ending a session asks AgentCore to stop it and marks the Topline record ended with reason `user`. If the provider stop request fails, Topline still marks an operator-ended session ended so the interface does not keep presenting a stale active session. Expired or missing sessions show **Browser session unavailable** and offer a path back to the launcher. ## Common errors | Message | Meaning | Recovery | | --- | --- | --- | | `capability_required:harness.browser` | The user lacks browser access. | Grant the capability through the normal admin process. | | `agentcore_browser_not_configured` | No AgentCore browser is configured on the API server. | Configure `AGENTCORE_BROWSER_ARN` or `AGENTCORE_BROWSER_IDENTIFIER` and verify AWS access. | | `browser_profile_required` | No profile was selected. | Select or create a profile. | | `browser_profile_not_found` | The profile is not owned by this user and tenant, or no longer exists. | Refresh and choose an available profile. | | `browser_profile_busy` | Another session holds the save lease. | Wait and retry. | | `browser_session_inactive` | The session ended or expired. | Open a new browser session. | | `browser_sensitive_input_requires_human` | An agent tried to type sensitive data or the active field could not be verified as safe. | Enter the value manually in the secure-browser page. | | `browser_approval_unavailable` | The approval was rejected, expired, already claimed, or out of scope. | Have the agent create a new proposal if the action is still needed. | ## Operations checklist 1. Apply the browser profile/session migrations and the brokered-approval migrations before enablement. 2. Configure an AgentCore browser ARN or identifier and the correct AWS region. 3. Grant `harness.browser` only to intended operators. 4. Leave `BROKERED_BROWSER_APPROVALS_ENABLED` off until cross-tenant and cross-user certification passes. 5. Schedule daily browser-approval cleanup. 6. Smoke-test profile creation, starting URL navigation, screenshot refresh, human typing, profile save, task attachment, approval rejection, approval execution, and session termination. ## Current limitations - The view refreshes by screenshots rather than continuous streaming. - The human toolbar exposes only click, type, and a small key set. - Sessions expire after one hour. - A browser profile cannot be saved concurrently from multiple sessions. - There is no retired VM/noVNC fallback.