Browser Accounts

Voxos exposes one general use_browser tool in text chat and authenticated in-app voice. It accepts a complete browser instruction and either:

• a public HTTPS start URL for ordinary browsing; or
• an opaque handle for a saved Browser Account assigned to the exact agent.

A Browser Account is an optional credential profile, not a separate type of browser agent. Selecting a profile adds its authorized origins and encrypted login state to the same general browser-task contract. Website behavior belongs in the agent instruction or a reusable skill; it is not encoded in provider or application code.

Browser Accounts are enabled by default and require no values in .env. Voxos supports three profile providers:

• Voxos Local Browser (recommended) stores an encrypted website username and password in the user secret vault. Root Docker Compose runs a private Stagehand task service and pinned Steel Chromium process. Every task gets an ephemeral browser session; no Chromium profile directory is shared.
• Browserless stored credentials stores the same encrypted credential pair in Voxos and supplies it to Browserless only while an authorized task is running.
• Browser Use managed profile lets the user sign in manually in a short-lived Browser Use Cloud live session. Browser Use retains the profile; Voxos stores an encrypted opaque profile reference, not the website password.

The browser task runtime uses the encrypted credential for the text provider currently selected in Voxos. It keeps a selected model that is explicitly catalogued for browser use; otherwise it chooses that provider’s browser-model route. NVIDIA therefore keeps GPT-OSS 20B for ordinary chat but uses Step 3.7 Flash inside browser tasks. Routing never changes providers or crosses credential boundaries.

General Browser Tasks

For public browsing, ask the agent to use the browser and identify where to start. The model passes a complete instruction and public HTTPS start_url to use_browser. Text chat can add a narrow set of exact allowed_origins when a legitimate workflow crosses sites. Public tasks do not use saved credentials or acquire a Browser Account lease.

For signed-in work, ask naturally, for example, “Use my Eon Next profile to sign in and tell me the next payment shown.” The tool description lists only safe labels, primary origins, and opaque handles for profiles assigned to that agent. Voxos resolves the selected profile, provider, origins, session, and secrets outside model-controlled arguments and checks the assignment again at execution. The model never receives the username, password, provider token, profile ID, or model API key.

Browser tasks default to read_only. Read-only tasks may navigate, authenticate, dismiss overlays, and inspect information, but their browser policy forbids purchases, payments, messages, uploads, cancellations, profile changes, and other writes. state_changes_allowed is available only when the user explicitly requested a state-changing browser action. This policy is an agent control, not an enforceable transaction checkpoint, so saved website identities should still have the least privilege practical for their intended work.

The built-in browser-use skill tells the Voxos agent how to formulate a complete task, select public browsing or an assigned profile, keep origins narrow, and choose the action mode. Additional user skills can provide reusable site or workflow guidance without changing the browser service.

Local Browser Setup

1. Start the normal Docker Compose stack. It includes private browser-agent and steel-browser services; neither publishes a host port.
2. Open Browser Accounts and keep Voxos Local Browser (recommended) selected.
3. Enter a label, one exact public HTTPS website origin, any reviewed login or SSO origins, the website username and password, and the agents that may use the profile.
4. Ask the assigned agent to complete a browser task with that profile. No per-message selector or repeated approval is required.
5. For unattended work, explicitly attach the ready local profile to a schedule in Operations. The queued run receives an immutable account snapshot and must execute its persisted browser instruction.
6. Use Edit details to change the label, primary origin, reviewed login origins, or assignments. Replace stored credentials separately after a password change. Revoke or delete the profile when it is no longer needed.

Local execution sends the agent’s instruction unchanged to the generic Stagehand service together with a bounded step count, exact origin set, action mode, selected model transport, and optional named secret variables. The service contains no website, login, dashboard, billing, or extraction workflow. The pinned self-hosted Steel runtime supports one active session, so the service serializes local tasks. Signed-in use also holds an account-specific database lease to prevent concurrent use across API or worker replicas.

The reviewed origins are exact public HTTPS origins. A CDP guard pauses new pages and popups and blocks top-level HTTP or HTTPS navigation outside that set before it loads. Cross-origin scripts, frames, images, and API requests required by an approved page may still load; the guard is a navigation boundary, not a complete network sandbox. Add every legitimate identity-provider origin used during login. MFA, passkeys, CAPTCHA, device approval, and automation blocking can still stop an unattended task. Voxos reports a blocked task rather than guessing the result.

Browserless Setup

1. Open MCP, add Browserless, save its API token as bearer authentication, enable and trust the connection, test it, and allow browserless_agent for the intended agent.
2. Create a Browser Account using that connection. Supply the label, exact website and reviewed SSO origins, username, password, and agent assignments.
3. Ask the assigned agent to use the profile. Voxos calls the same general use_browser tool; the saved profile selects Browserless behind the server boundary.
4. For unattended work, attach the ready Browserless profile to a schedule for the same assigned agent.

The Browser Accounts form lists only supported provider connections whose required execution tool is allowed. If the form asks for browserless_agent, add that tool to the connection’s allowed tools and agent grant, save the MCP tools, and refresh the form. Website credentials are not submitted while the provider requirement is unresolved.

Browserless runs its hosted agent over the authenticated /chromium/cli WebSocket endpoint. Voxos sends the instruction, start origin, reviewed origin set, bounded step count, action policy, and vault credentials for that task. Returned text is bounded, and exact occurrences of the supplied username and password are redacted before it enters model context. Browserless can still observe credentials, browser content, and the authenticated session during the task. See the Browserless hosted agent API.

The default endpoint is the Browserless London fleet. BROWSER_ACCOUNTS_BROWSERLESS_BASE_URL can select another official fleet or a trusted self-hosted deployment. Browserless stored-credential automation works only when the site can complete authentication with the stored username and password. Voxos does not store TOTP seeds, recovery codes, passkeys, or security question answers.

Browser Use Cloud Setup

1. Open MCP, configure Browser Use Cloud with API-key-header authentication, enable and trust it, test it, and grant run_session to the intended agent.
2. Create a Browser Account with its two-letter browser country, exact website origin, and every exact login or SSO origin. Select Start secure sign-in.
3. Sign in and complete MFA or a passkey in the non-recorded Browser Use live session. Return to Voxos and select I’m signed in.
4. Ask for a browser task in Chat or authenticated in-app voice and select the saved profile through natural language.
5. Reauthenticate if the managed profile expires. Revoke or delete the account to stop known sessions and request remote profile deletion.

Changing the browser country invalidates a managed profile and requires secure sign-in again. Browser Use managed profiles are not available to unattended schedules; schedules support stored-credential local and Browserless profiles.

Authorization And Scheduling

Saved-profile browser execution requires the intersection of:

• a verified local Voxos user and tenant-scoped database session;
• a persisted web-chat root run, authenticated owner voice session, or scheduled root run owned by that user;
• a ready Browser Account assigned to the exact agent;
• an opaque profile handle currently advertised to that agent;
• for hosted profiles, the enabled, trusted, connected MCP provider and exact high-risk tool grant; and
• an available account lease.

Text chat sends the browser instruction provided in the use_browser call and binds signed-in execution to the durable run and exact client turn. Owner voice binds it to the latest finalized user utterance and server-issued message ID. The selected account and request are consumed before provider execution, and the same account cannot be replayed for that turn. Subagents and phone callers do not receive saved-profile authority.

A schedule stores an explicitly selected local or Browserless Browser Account ID after validating tenant ownership and exact-agent assignment. Each queued run snapshots that ID, so later schedule edits cannot change authority already assigned to a run. The backend obtains the exact task from the persisted run and requires browser execution in the first model round.

Stored Data And Secrets

Voxos stores the profile label, provider, optional provider-connection ID, normalized origins, authentication mode, status, assigned agents, lifecycle timestamps, leases, and category-only audit events. Interactive signed-in execution stores a consumed authorization with user, account, agent, session, client-turn identifier, task, origins, and optional durable run. Browser Use profiles also store the two-letter browser country.

Secrets use separate context-bound vault purposes:

• local and Browserless username/password payloads use BROWSER_ACCOUNT_CREDENTIAL;
• Browser Use profile references use BROWSER_PROFILE_REFERENCE;
• temporary provider task and session handles use BROWSER_SESSION_REFERENCE; and
• the local runtime resolves the selected text-provider key and its capability-routed browser model from the existing vault entry only for the task.

Plaintext credentials, provider tokens, profile or session IDs, CDP URLs, and live-view URLs are never Browser Account response fields. Browser Account validation errors omit submitted values, and credential and setup responses use Cache-Control: no-store.

Database encryption protects against a database-only compromise. It does not protect credentials from an authorized Voxos backend, the active local browser runtime or hosted provider, or the target website. Browser output can enter durable chat, transcript, run, and tool-event records under their normal retention rules.

Safety And Residual Risk

Threat or asset	Primary controls	Residual risk
Database-only compromise	AES-GCM or KMS-envelope vault, context-bound secret purposes, forced tenant RLS	Key or backend compromise changes the outcome.
Cross-tenant or wrong-agent access	Firebase-derived local user, scoped sessions, fresh ownership and assignment checks, forced RLS	A superuser or BYPASSRLS application role invalidates database isolation.
Model supplies authority	One typed tool, opaque assigned-profile handles, fresh grant checks, server-owned credentials and sessions	The model chooses among advertised profiles; webpage content can still influence the browser agent.
Prompt injection	Page content is explicitly untrusted, instructions and variables are separated, origin and action policies are included	Prompt policy is not a complete browser action or network interceptor.
Scheduled credential use	Authenticated schedule creation, explicit profile binding, immutable per-run snapshot, required first-round execution	Anyone authorized to edit the schedule can change future runs.
Browser runtime or provider compromise	Private local services or separate hosted provider token, bounded sessions, local top-level navigation guard, least-privilege identities	The runtime or provider sees active credentials, authenticated state, and page content.
Secret in provider output	Exact credential redaction and output cap	Transformed, encoded, partial, or page-derived sensitive data may still be returned.
Concurrent profile use	One heartbeating database lease per Browser Account; serialized local runtime; expired-lease reconciliation	Activity outside Voxos can still race with Voxos.
Remote cleanup failure	Browser Use deletion retry and backlog metric; Browserless waits for its executor-owned WebSocket to close	Provider-side state may require console cleanup.

Incident Runbook

For a suspected credential, provider-token, session, or browser-content compromise:

1. Revoke the affected Browser Account. Set BROWSER_ACCOUNTS_ENABLED=false only when a broader account-feature kill switch is required.
2. For hosted mode, disable or revoke the associated Browserless or Browser Use MCP connection. For local mode, isolate the private browser services while investigating.
3. Revoke target-site sessions and rotate the website password. Replace the stored credentials only after root-cause review.
4. For Browser Use, stop remaining sessions and verify remote profile deletion. Preserve deletion_pending so cleanup can retry.
5. Review category-only audit events and operational metrics. Do not copy page content, full URLs, task text, or secret values into logs or incident tickets.
6. Re-enable the profile only after session or key rotation and validation with a non-production identity.