Browser Profiles & Agent Browser

A browser profile is a dedicated, persistent browser identity (cookies, local storage, session state) owned by exactly one user. Profiles are personal: every API and agent tool only ever sees the caller's own profiles.

• Local profiles (default provider) keep their Chromium user-data-dir on the instance under the shared workspace volume (.browser-profiles/<id>), so login state never leaves the Clapilot server.
• Browser Use Cloud profiles (browser-use provider, admin-configured) live at Browser Use and are only used by browser_use_run.

Profiles are created and managed in Settings → App Connections (/settings/app-verbindungen), in the browser profiles card. Creating one requires explicit consent, which is audited.

Creating a local profile is all-or-nothing: Clapilot first creates the profile's user-data directory (<CLAPILOT_WORKSPACE_DIR>/.browser-profiles/<id>) and only then stores the profile together with its profile_created audit event in a single database statement. If the directory cannot be created (for example because CLAPILOT_WORKSPACE_DIR is unset or not writable on that server), nothing is saved and the settings card shows "profile storage on this server is not writable" (HTTP 500); if saving fails (for example a duplicate name), the new directory is removed again. A failed attempt therefore never leaves a half-created profile behind. The same applies when the agent auto-creates its default Agent profile.

Signing in once (interactive live view)

Local profiles sign in through an interactive live view: Clapilot launches the profile's Chromium inside the web container and streams it into a dialog where the user types, clicks, and pastes like in a normal browser. Finishing the sign-in closes the browser so the state is flushed to disk and marks the profile ready. The same dialog opens from an agent chat card when the agent calls request_browser_signin (login, 2FA, or CAPTCHA the agent cannot supply).

The agent's browser

The agent drives a real Chromium on the instance with the local browser tools (browser_open, browser_navigate, browser_snapshot, browser_scroll, browser_click, browser_type, browser_read, browser_close). Each user has at most one agent browser session at a time, on one of their local profiles; it closes after 5 minutes without agent activity or 20 minutes in total. When browser_open gets an explicit profile_id, that profile is used as given. Without one, the agent picks the user's most recently updated local profile whose sign-in is confirmed (ready); only if there is none does it fall back to the most recent profile still awaiting sign-in, and only if there is no such profile either does it create a default Agent profile. Disabled profiles are never picked automatically, and a newer profile that was never signed in cannot displace the one the user logged in with. See Agent tool contracts for the tool details.

Live agent browser window

While the agent has a browser session open, a floating window shows that browser live so the user can follow along.

• What it shows: a live picture of the page the agent is working on (CDP screencast, JPEG, at most ~12 frames per second), a live indicator with "Agent steuert den Browser", the browser profile name, and the current URL (read-only, truncated; hover shows the full address).
• View only: the window never sends input to the agent's browser. To sign in or solve a challenge, use the sign-in card the agent posts (request_browser_signin), which opens the interactive live view.
• When it appears: the web app checks for an active agent session every few seconds while the tab is visible (slower after a period without sessions, paused while the tab is hidden). Chat surfaces also trigger an immediate check as soon as a browser_* tool event streams in, so the window usually opens with the agent's first browser step.
• Controls (circular icon buttons in the header):
  • Minimize collapses the window to a small pill with the live indicator and the current host name; clicking the pill restores it.
  • Maximize / Restore size toggles between the compact window (about 520 px wide) and a near-fullscreen view. Esc leaves the maximized view.
  • Close hides the window for the current agent session. It stays hidden for that session (remembered per browser tab); the next agent browser session opens it again.
• Placement: by default the window sits bottom-right, next to the floating chat dock. It can be dragged by its header; the position is remembered in the browser and kept inside the viewport. On phones (< 768 px) it starts as the minimized pill above the bottom tab bar and expands into a full-width sheet.
• When the session ends (the agent closes the browser, the session idles out, the agent switches profiles, or the profile is handed over for a human sign-in) the window stays open: it keeps the last frame and shows "Browser geschlossen" with the reason in a status strip until the user closes it. If the agent opens a new browser session meanwhile, the same window switches to it and keeps its current size (normal, minimized, or maximized).
• Privacy: sessions are keyed by the authenticated user. Only the owner of an agent browser session can see its status or watch it; other users, including admins, never get another user's session. Watching does not count as agent activity and does not extend the session.
• Cost: the screencast only runs while at least one window is connected; an unwatched agent session costs nothing extra.

The window is available in the classic and the tab layout of the web app. The iOS and macOS clients have no browser live view surface yet.

Agent access

No agent tool is involved or needed: the window visualizes the agent's own browser_* activity. The endpoints are listed in the API reference (/api/browser-profiles/agent-session and /api/browser-profiles/agent-session/stream).