Skip to content

Self-improving AI Employees for everyone

fix(browser): render installed browsers inside the workspace by default

trohitg7ff44b81c221
diff --git a/.env.template b/.env.template
index c2ce279c..ea7b90c4 100644
--- a/.env.template
+++ b/.env.template
@@ -213,9 +213,9 @@ MAX_CONCURRENT_SUBAGENTS=3
MAX_DELEGATION_DEPTH=2
# Browser node. Uses installed Chrome/Edge/Chromium with a dedicated persistent
-# profile and a visible window by default; the workspace also shows its stream.
+# profile displayed in the workspace UI by default, without a separate window.
# BROWSER_RUNTIME=testing explicitly opts into pinned Chrome for Testing.
-# BROWSER_HEADLESS=true supports servers without a desktop display.
+# BROWSER_HEADLESS=false additionally opens a desktop browser window.
# BROWSER_MAX_INSTANCES caps running profiles — when
# another would exceed it, the least recently used idle profile is stopped
# first. BROWSER_IDLE_TIMEOUT_MS stops a profile's Chrome after that many
@@ -224,6 +224,7 @@ MAX_DELEGATION_DEPTH=2
# BROWSER_SANDBOX: auto turns Chrome's sandbox off only as root on Linux
# (Docker, the GCP VM), where it cannot start; on/off force it.
# BROWSER_CHROME_PATH explicitly selects a browser instead of auto-discovery.
+# Set it to installed Chrome's executable to prevent switching to Edge/Chromium.
# Auto-discovery skips browsers older than the selected profile requires.
# System mode never falls back to a testing-browser download.
# BROWSER_DOWNLOAD_MAX_MB caps each file a
@@ -234,7 +235,7 @@ BROWSER_INSTALL_TIMEOUT_SECONDS=900
BROWSER_SANDBOX=auto
BROWSER_CHROME_PATH=
BROWSER_RUNTIME=system
-BROWSER_HEADLESS=false
+BROWSER_HEADLESS=true
BROWSER_DOWNLOAD_MAX_MB=200
# Dead-letter queue for failed workflow executions. Off by default.
diff --git a/CLAUDE.md b/CLAUDE.md
index 4d297e30..976d6686 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,7 +28,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Pricing Service](./docs-internal/pricing_service.md)** | Centralized cost tracking for LLM tokens and API services (Twitter, Google Maps) with HTTPX event hooks |
| **[Proxy Service](./docs-internal/proxy_service.md)** | Residential proxy provider management with template-based URL formatting, health scoring, and transparent HTTP node injection |
| **[Email Service](./docs-internal/email_service.md)** | IMAP/SMTP integration via Himalaya CLI with EmailService orchestrator, provider presets, custom credential fallback, and polling triggers |
-| **[Browser](./docs-internal/browser.md)** | Current `browser` node: installed Chrome/Edge/Chromium in a dedicated visible profile by default (`BROWSER_RUNTIME=system`, `BROWSER_HEADLESS=false`) and pinned browser-use CLI. Chrome for Testing requires explicit `BROWSER_RUNTIME=testing`. System mode retains the native user agent and OS password-store/keychain integration; basic/mock keychain flags are restricted to testing mode. Includes persistent employee/shared profiles, session leases, agent/user handoff, network policy, screenshots as workspace FileRefs and authenticated `/ws/browser` live viewing. Plugin-owned installation is lazy (`_install_chrome.py`, `_install_bu.py`); importing or shutting down the plugin never installs it. Replaces the former agent-browser and separate `browserHarness` implementations. |
+| **[Browser](./docs-internal/browser.md)** | Current `browser` node: installed Chrome/Edge/Chromium in a dedicated profile rendered inside the workspace by default (`BROWSER_RUNTIME=system`, `BROWSER_HEADLESS=true`) and pinned browser-use CLI. Chrome for Testing requires explicit `BROWSER_RUNTIME=testing`. System mode retains the native user agent and OS password-store/keychain integration; basic/mock keychain flags are restricted to testing mode. Includes persistent employee/shared profiles, session leases, agent/user handoff, network policy, screenshots as workspace FileRefs and authenticated `/ws/browser` live viewing. Plugin-owned installation is lazy (`_install_chrome.py`, `_install_bu.py`); importing or shutting down the plugin never installs it. Replaces the former agent-browser and separate `browserHarness` implementations. |
| **[Browser Workspace](./docs-internal/browser_workspace.md)** | Home and Dev share `WorkspaceTabs` and `BrowserWorkspace`: Browser / Canvas / Android, capability-based discovery, binary JPEG frames, bounded frame credit and decoding, Take control / Hand back, visibility cleanup and payload-free opt-in diagnostics. Android remains a placeholder. |
| **[WhatsApp Business Service](./docs-internal/whatsapp_business_service.md)** | Official Meta Cloud API plugin in [`server/nodes/whatsapp_business/`](./server/nodes/whatsapp_business/) — **distinct from `nodes/whatsapp/`**, which is a personal account over an unofficial Go bridge; they share no node type, credential or palette group. Four nodes: `whatsappBusinessSend` (10 ops — Meta models message type as a *field* on one `/messages` endpoint, so text / media / template / interactive are operations, not nodes), `whatsappBusinessMedia` (the one genuinely separate endpoint family), and the `Receive` / `Status` triggers (kept separate because a canary trigger registers exactly one CloudEvents type). `phone_number_id` is deliberately **absent from Params** — on a dual-purpose ActionNode `execute_as_tool` merges `{**node_params, **tool_args}`, so a declared field is model-settable and a prompt injection could choose the sending identity; it comes from the credential only. Webhook via `register_webhook_source` on the shared catch-all, `X-Hub-Signature-256` HMAC failing closed, composite `wamid:status` dedup ids so `sent→delivered→read` don't collapse. |
| **[Stripe Service](./docs-internal/stripe_service.md)** | Stripe CLI integration — `stripeAction` (CLI pass-through) + `stripeReceive` (signed-webhook trigger). Reference plugin for the Wave 12 event framework AND the **CLI-managed-auth pattern**: browser OAuth via `stripe login --non-interactive` + `--complete <url>` (URL extracted from `next_step` shell command via `shlex.split`) + auto-installed binary (`ensure_stripe_cli` from GitHub releases) + marker-token reuse of `auth_service.store_oauth_tokens` + CloudEvents-shaped `broadcast_credential_event("credential.oauth.connected" \| ".disconnected", provider=...)` — zero per-provider hardcoding in the frontend. Daemon stdout/stderr ingested via `ProcessService`'s `line_handler` callback (no log-file tailing); credential gate routed through `await self.has_credential()` so non-api-key auth (`is_logged_in()`) plugs in via subclass override. |
@@ -2720,7 +2720,7 @@ This function:
- Supports TTL expiration and automatic cleanup of expired entries
- **Conditional Redis (historical)**: the Docker Compose topology (Redis profiles, `scripts/docker.js` wrapper) is historical — see [docs-internal/deployment_legacy.md](./docs-internal/deployment_legacy.md)
- **WebSocket Reconnect via PartySocket** (`partysocket/ws` from Cloudflare): native-WS-compatible class handles jittered exponential backoff, message replay (`maxEnqueuedMessages: 200`), and intentional-close (RFC 6455 §7.4.1 code 1000) automatically. Replaces the previous flat 3 s `setTimeout(connect, 3000)` loop. Reconnect envelope (`MIN_DELAY_MS: 250`, `MAX_DELAY_MS: 8000`, `GROW_FACTOR: 1.3`) lives in `client/src/lib/connectionConfig.ts`. The +12 s WS-drop-and-reconnect cycle observed under React Strict Mode is gone — verified across two consecutive cold launches with zero `Client disconnected` events through 130+ s of activity. See `docs-internal/performance.md` for measurements.
-- **Docker image runs uvicorn, not `company serve`**: `docker/entrypoint.sh` writes the three secrets into `/data/opencompany.env` once (the container env's value when set there, else a random one), then execs the desktop shell's uvicorn argv (`--timeout-graceful-shutdown 5`, port resolved through `core.env_defaults`). `company serve` would need root `node_modules` + the CLI venv, ignores `OPENCOMPANY_ENV_FILE`, and its supervisor tree-kills the backend 5 s after SIGTERM. `HOST` stays `127.0.0.1` (the backend dials itself at `ws://HOST:PORT/ws/internal`); the external bind is the `--host 0.0.0.0` argument. The image has no Node: `/usr/local/bin/node` links to bun, so the `#!/usr/bin/env node` bin scripts (vercel, cf) run. The Dockerfile now sets `BROWSER_RUNTIME=system`, `BROWSER_CHROME_PATH=/usr/bin/chromium` and `BROWSER_HEADLESS=true`; the browser extra supplies Chromium. This explicitly overrides the desktop-visible default. The retired agent-browser variable `AGENT_BROWSER_EXECUTABLE_PATH` is no longer in the image. Installed-browser discovery, opt-in Chrome for Testing/browser-use installation and explicit headless deployment requirements are documented in [Browser](./docs-internal/browser.md). The compose project is named `opencompany-selfhost` so it never merges with another compose project called `opencompany`. See [docker.md](./docs-internal/docker.md).
+- **Docker image runs uvicorn, not `company serve`**: `docker/entrypoint.sh` writes the three secrets into `/data/opencompany.env` once (the container env's value when set there, else a random one), then execs the desktop shell's uvicorn argv (`--timeout-graceful-shutdown 5`, port resolved through `core.env_defaults`). `company serve` would need root `node_modules` + the CLI venv, ignores `OPENCOMPANY_ENV_FILE`, and its supervisor tree-kills the backend 5 s after SIGTERM. `HOST` stays `127.0.0.1` (the backend dials itself at `ws://HOST:PORT/ws/internal`); the external bind is the `--host 0.0.0.0` argument. The image has no Node: `/usr/local/bin/node` links to bun, so the `#!/usr/bin/env node` bin scripts (vercel, cf) run. The Dockerfile now sets `BROWSER_RUNTIME=system`, `BROWSER_CHROME_PATH=/usr/bin/chromium` and `BROWSER_HEADLESS=true`; the browser extra supplies Chromium. This matches the default of rendering inside the workspace without a desktop window. The retired agent-browser variable `AGENT_BROWSER_EXECUTABLE_PATH` is no longer in the image. Installed-browser discovery, opt-in Chrome for Testing/browser-use installation and explicit headless deployment requirements are documented in [Browser](./docs-internal/browser.md). The compose project is named `opencompany-selfhost` so it never merges with another compose project called `opencompany`. See [docker.md](./docs-internal/docker.md).
- **Configurable Authentication**: `VITE_AUTH_ENABLED` environment variable
- Set to `false` to bypass login entirely (useful for local development)
- Frontend creates anonymous user with owner privileges when disabled
diff --git a/docs-internal/browser.md b/docs-internal/browser.md
index 3d9072f8..9bccd97c 100644
--- a/docs-internal/browser.md
+++ b/docs-internal/browser.md
@@ -1,8 +1,9 @@
# Native browser runtime
The `browser` node launches installed Chrome, Edge or Chromium in an
-OpenCompany-owned profile. The default opens a visible browser window; it
-does not attach to or copy your personal browser profile. Agents use the
+OpenCompany-owned profile. By default it runs headless and is displayed inside
+the workspace, without a separate desktop window. It does not attach to or copy
+your personal browser profile. Agents use the
browser-use CLI for ordinary browser operations; people watch and control the
same Chrome through the [Browser workspace](./browser_workspace.md). The old
agent-browser driver and separate `browserHarness` node are retired.
@@ -50,7 +51,7 @@ its opt-in flag directly from the process environment:
| Setting | Default | Purpose |
| --- | --- | --- |
| `BROWSER_RUNTIME` | `system` | Installed browser discovery; `testing` explicitly enables pinned Chrome for Testing |
-| `BROWSER_HEADLESS` | `false` | Visible browser by default; set `true` explicitly for containers or unattended hosts |
+| `BROWSER_HEADLESS` | `true` | Render in the workspace without a desktop window; `false` additionally opens a separate window |
| `BROWSER_CHROME_PATH` | Empty | Explicit Chrome/Edge/Chromium executable override |
| `BROWSER_MAX_INSTANCES` | `3` | Bound simultaneously running browser profiles |
| `BROWSER_IDLE_TIMEOUT_MS` | `600000` | Reap idle profiles; attached viewers and pending user work count as busy |
diff --git a/docs-internal/browser_harness.md b/docs-internal/browser_harness.md
index 68437504..af0a6931 100644
--- a/docs-internal/browser_harness.md
+++ b/docs-internal/browser_harness.md
@@ -8,7 +8,7 @@ Current documentation:
- [Browser node flow](node-logic-flows/web_automation/browser.md): operations, operator settings, dispatch, outputs and legacy migration.
- [Browser workspace](browser_workspace.md): live viewing, frame delivery, direct input and human control.
-The current runtime launches installed Chrome/Edge/Chromium in a dedicated OpenCompany profile with a visible window by default; it neither attaches to nor copies an already running, logged-in personal profile. Chrome for Testing is available only through explicit `BROWSER_RUNTIME=testing`; headless operation requires `BROWSER_HEADLESS=true`. Agent/workflow operations use generated scripts through the isolated, pinned browser-use CLI and its persistent daemon; WebMCP and live viewer capture/control have native CDP paths. The presence of browser-harness machinery inside that dependency is separate from the retired OpenCompany node.
+The current runtime launches installed Chrome/Edge/Chromium in a dedicated OpenCompany profile headless inside the workspace UI by default; it neither attaches to nor copies an already running, logged-in personal profile. Chrome for Testing is available only through explicit `BROWSER_RUNTIME=testing`; a separate desktop window requires `BROWSER_HEADLESS=false`. Agent/workflow operations use generated scripts through the isolated, pinned browser-use CLI and its persistent daemon; WebMCP and live viewer capture/control have native CDP paths. The presence of browser-harness machinery inside that dependency is separate from the retired OpenCompany node.
[Saved-workflow migration](../server/services/workflow_migrations.py) renames `browserHarness` to `browser` and maps `goto` to `navigate`, `js` to `evaluate`, `doctor` to `diagnose`, and `tabs` to tab listing. Existing Python code is retained with a helper-compatibility warning. `evaluate` and `run_python` are now workflow-only; duplicate Browser tool edges created by migration are removed with a warning. See the node flow for complete parameter compatibility behavior.
diff --git a/docs-internal/browser_workspace.md b/docs-internal/browser_workspace.md
index d6ba841d..8bf8b8ca 100644
--- a/docs-internal/browser_workspace.md
+++ b/docs-internal/browser_workspace.md
@@ -2,10 +2,12 @@
For installation, profiles, policy and agent execution, see the
[native browser runtime](./browser.md). This document describes the shared
-workspace surface and its live-stream contract. By default the runtime opens
-installed Chrome/Edge/Chromium in a dedicated OpenCompany profile and a visible
-window. It does not attach to your personal profile. Headless operation requires
-`BROWSER_HEADLESS=true`; Chrome for Testing requires `BROWSER_RUNTIME=testing`.
+workspace surface and its live-stream contract. By default the runtime launches
+installed Chrome/Edge/Chromium headless in a dedicated OpenCompany profile and
+renders it inside this workspace. It does not attach to your personal profile.
+`BROWSER_HEADLESS=false` additionally opens a desktop window; Chrome for Testing
+requires `BROWSER_RUNTIME=testing`. Set `BROWSER_CHROME_PATH` to installed Chrome
+to keep Chrome selected even when another installed browser has a newer version.
Normal mode and Dev mode share `components/workspace/WorkspaceTabs.tsx`
(Browser, Canvas, Android) and `components/browser/BrowserWorkspace.tsx`.
diff --git a/docs-internal/desktop_host_contract.md b/docs-internal/desktop_host_contract.md
index 4893a131..50bb6325 100644
--- a/docs-internal/desktop_host_contract.md
+++ b/docs-internal/desktop_host_contract.md
@@ -179,8 +179,8 @@ the codex provider (`bun x @openai/codex` when no system `codex` exists), and
the Browser runtime's pinned `uv tool install browser-use==<pin>` installation.
The Browser installer respects `UV_TOOL_DIR` / `UV_TOOL_BIN_DIR`; otherwise it
uses `<DATA_DIR>/packages/browser-use/{tools,bin}`. OpenCompany supervises installed Chrome/Edge/Chromium in a dedicated profile,
-opening a visible window by default. `BROWSER_CHROME_PATH` overrides discovery;
-`BROWSER_HEADLESS=true` is explicit. Chrome for Testing is downloaded only with
+rendering headless inside the workspace by default. `BROWSER_CHROME_PATH` overrides discovery;
+`BROWSER_HEADLESS=false` additionally opens a desktop window. Chrome for Testing is downloaded only with
`BROWSER_RUNTIME=testing`, never as a fallback when no installed browser exists. See [browser.md](./browser.md) and
[browser_workspace.md](./browser_workspace.md). `BUN_INSTALL` / `BUN_INSTALL_CACHE_DIR`
keep bun's own cache and global state under the app's data dir rather than a
diff --git a/docs-internal/docker.md b/docs-internal/docker.md
index 37092110..5134b4ec 100644
--- a/docs-internal/docker.md
+++ b/docs-internal/docker.md
@@ -69,10 +69,10 @@ The image sets these on top of the template:
| `NODEJS_USER_PACKAGES_DIR` | `/data/nodejs-user-packages` | Packages installed for code nodes persist |
| `BROWSER_RUNTIME` | `system` | Use the image's installed browser; no testing-browser fallback |
| `BROWSER_CHROME_PATH` | `/usr/bin/chromium` | Select Chromium supplied by the browser extra |
-| `BROWSER_HEADLESS` | `true` | Explicit container override of the desktop-visible default |
+| `BROWSER_HEADLESS` | `true` | Render inside the workspace without a desktop window |
| `PYTHONUNBUFFERED` | `1` | Log lines reach `docker compose logs` as they are written |
-**Browser runtime configuration:** the Dockerfile sets `BROWSER_RUNTIME=system`, `BROWSER_CHROME_PATH=/usr/bin/chromium` and `BROWSER_HEADLESS=true` for the browser extra. These are already the image defaults; compose `environment:` can override them. The headless image setting explicitly overrides the application's desktop-visible default, which requires a display. Discovery can find installed Chromium, but the explicit path makes image selection deterministic. The former `AGENT_BROWSER_EXECUTABLE_PATH` has been removed from the Dockerfile and is not read by this runtime. `BROWSER_RUNTIME=testing` is the only mode that downloads pinned Chrome for Testing; it is never a missing-browser fallback. Validate the built image and Linux libraries before deployment.
+**Browser runtime configuration:** the Dockerfile sets `BROWSER_RUNTIME=system`, `BROWSER_CHROME_PATH=/usr/bin/chromium` and `BROWSER_HEADLESS=true` for the browser extra. These are already the image defaults; compose `environment:` can override them. The headless image setting matches the application default: render in the workspace without a desktop window. Discovery can find installed Chromium, but the explicit path makes image selection deterministic. The former `AGENT_BROWSER_EXECUTABLE_PATH` has been removed from the Dockerfile and is not read by this runtime. `BROWSER_RUNTIME=testing` is the only mode that downloads pinned Chrome for Testing; it is never a missing-browser fallback. Validate the built image and Linux libraries before deployment.
The image has no Node. It links `/usr/local/bin/node` to bun, so the plugin CLIs whose entry scripts start `#!/usr/bin/env node` (vercel, cf) run on bun, as in the official oven/bun images. Browser automation installs browser-use through uv instead.
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index 85a74e45..0f6360cc 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -500,7 +500,7 @@ See [media_transport.md](./media_transport.md).
## Browser workspace live view
-Home and Dev share [WorkspaceTabs](../client/src/components/workspace/WorkspaceTabs.tsx) and [BrowserWorkspace](../client/src/components/browser/BrowserWorkspace.tsx). Browser nodes are discovered through the backend `isBrowserPanel` capability; viewing attaches to a saved workflow/node without launching Chrome. The runtime defaults to installed Chrome/Edge/Chromium with a dedicated profile and visible window; headless and testing-browser modes are explicit server settings. The Browser tab supports server-authorized Take control / Hand back for navigation, mouse, keyboard, paste and login. Canvas retains its renderer; Android remains an explanatory placeholder.
+Home and Dev share [WorkspaceTabs](../client/src/components/workspace/WorkspaceTabs.tsx) and [BrowserWorkspace](../client/src/components/browser/BrowserWorkspace.tsx). Browser nodes are discovered through the backend `isBrowserPanel` capability; viewing attaches to a saved workflow/node without launching Chrome. The runtime defaults to installed Chrome/Edge/Chromium with a dedicated profile rendered headless inside the workspace; a separate desktop window and testing-browser mode are explicit server settings. The Browser tab supports server-authorized Take control / Hand back for navigation, mouse, keyboard, paste and login. Canvas retains its renderer; Android remains an explanatory placeholder.
The viewer uses a separate authenticated same-origin `/ws/browser` socket, not the general `WebSocketContext` frame stream. Binary JPEG envelopes are decoded sequentially with a two-frame local bound; consumed/skipped frames are acknowledged. Canvas dimensions change only when image dimensions change, and input coordinates use the metadata of the frame actually painted. Hidden, disposed or obsolete frames cannot restore a stale picture. Blur, pointer cancellation, hiding and unmount release user control; the server owns the release barrier and lease checks.
diff --git a/docs-internal/node-logic-flows/web_automation/browser.md b/docs-internal/node-logic-flows/web_automation/browser.md
index 72beba64..ea4da6e9 100644
--- a/docs-internal/node-logic-flows/web_automation/browser.md
+++ b/docs-internal/node-logic-flows/web_automation/browser.md
@@ -1,6 +1,6 @@
# Browser (`browser`)
-The Browser node launches installed Chrome/Edge/Chromium in a dedicated OpenCompany profile, visible by default, and exposes that profile to the live browser workspace. `BROWSER_RUNTIME=testing` explicitly selects Chrome for Testing; `BROWSER_HEADLESS=true` explicitly hides the window. It never attaches to a personal browser profile. It runs as a workflow step or as the agent tool named `browser`. The old `agent-browser` integration and separate `browserHarness` node have been replaced.
+The Browser node launches installed Chrome/Edge/Chromium in a dedicated OpenCompany profile, rendered headless in the workspace UI by default, and exposes that profile to the live browser workspace. `BROWSER_RUNTIME=testing` explicitly selects Chrome for Testing; `BROWSER_HEADLESS=false` additionally opens a desktop window. It never attaches to a personal browser profile. It runs as a workflow step or as the agent tool named `browser`. The old `agent-browser` integration and separate `browserHarness` node have been replaced.
See [native browser architecture](../../browser.md) for runtime installation, profile storage, networking and lifecycle, and [browser workspace](../../browser_workspace.md) for the viewer and UI protocol.
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index ce77ab40..c0f619b0 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -521,7 +521,7 @@ Queue distribution (live count via
| `code-exec` | Python / JS / TS sandboxes | 10 |
| `browser` | Installed Chrome/Edge/Chromium / browser-use / CDP | 4 |
-The current Browser plugin launches installed Chrome/Edge/Chromium in dedicated profiles with visible windows by default, owns browser-use tool execution and the CDP live view, and offers Chrome for Testing only through explicit testing mode. See [browser.md](./browser.md) and [browser_workspace.md](./browser_workspace.md); the retired `browserHarness` node is not a second active plugin.
+The current Browser plugin launches installed Chrome/Edge/Chromium in dedicated profiles rendered headless in the workspace UI by default, owns browser-use tool execution and the CDP live view, and offers Chrome for Testing only through explicit testing mode. See [browser.md](./browser.md) and [browser_workspace.md](./browser_workspace.md); the retired `browserHarness` node is not a second active plugin.
Env overrides: `TEMPORAL_<QUEUE>_CONCURRENCY` (e.g.
`TEMPORAL_AI_HEAVY_CONCURRENCY=8`).
diff --git a/server/core/config.py b/server/core/config.py
index beb21752..8f0b559f 100644
--- a/server/core/config.py
+++ b/server/core/config.py
@@ -455,7 +455,7 @@ class Settings(BaseSettings):
# auto disables Chrome's sandbox only as root on Linux, where it cannot
# start. system discovers installed Chrome/Edge/Chromium; testing opts into
# the pinned download. chrome_path selects an explicit executable.
- # Desktop browsers are visible unless headless is explicitly enabled.
+ # Render inside the workspace by default; a separate window is opt-in.
# Downloads a page starts are
# capped at download_max_mb each.
browser_max_instances: int = Field(default=3, env="BROWSER_MAX_INSTANCES", ge=1, le=50)
@@ -464,7 +464,7 @@ class Settings(BaseSettings):
browser_sandbox: str = Field(default="auto", env="BROWSER_SANDBOX", pattern="^(auto|on|off)$")
browser_chrome_path: str = Field(default="", env="BROWSER_CHROME_PATH")
browser_runtime: str = Field(default="system", env="BROWSER_RUNTIME", pattern="^(system|testing)$")
- browser_headless: bool = Field(default=False, env="BROWSER_HEADLESS")
+ browser_headless: bool = Field(default=True, env="BROWSER_HEADLESS")
browser_download_max_mb: int = Field(default=200, env="BROWSER_DOWNLOAD_MAX_MB", ge=1)
# Compaction Configuration. Threshold = model context_length ×
diff --git a/server/nodes/browser/_chrome.py b/server/nodes/browser/_chrome.py
index 33eb9ed2..fc14d3c7 100644
--- a/server/nodes/browser/_chrome.py
+++ b/server/nodes/browser/_chrome.py
@@ -1,7 +1,7 @@
"""Launching and stopping one profile's Chrome.
-An installed browser opens a visible window by default, with explicit headless
-mode available for servers. It uses its own ``--user-data-dir`` and a debugging port chosen by the OS
+An installed browser runs headless by default and is displayed in the workspace
+live view. A separate window is opt-in. It uses its own ``--user-data-dir`` and a debugging port chosen by the OS
(``--remote-debugging-port=0``; the real port is read back from the
``DevToolsActivePort`` file), and every request routed through the egress
proxy. The same browser is also available through the in-app live view.
@@ -108,7 +108,7 @@ def build_chrome_argv(
small_shm: bool,
platform: Optional[str] = None,
downloads_dir: Optional[Path] = None,
- headless: bool = False,
+ headless: bool = True,
override_user_agent: bool = False,
) -> List[str]:
platform = platform or sys.platform
@@ -261,7 +261,7 @@ class ChromeProcess(BaseProcessSupervisor):
major: int,
no_sandbox: bool,
small_shm: bool,
- headless: bool = False,
+ headless: bool = True,
override_user_agent: bool = False,
) -> None:
super().__init__()
diff --git a/server/nodes/browser/_runtime.py b/server/nodes/browser/_runtime.py
index cfa7bbd6..cfc1d184 100644
--- a/server/nodes/browser/_runtime.py
+++ b/server/nodes/browser/_runtime.py
@@ -260,14 +260,14 @@ class BrowserRuntime:
major=selected_major,
no_sandbox=no_sandbox,
small_shm=shm_small(),
- headless=bool(getattr(settings, "browser_headless", False)),
+ headless=bool(getattr(settings, "browser_headless", True)),
override_user_agent=provider == "testing",
)
self._chromes[profile.id] = chrome
else:
chrome._exe, chrome._proxy_port = exe, proxy_port
chrome._major = selected_major
- chrome._headless = bool(getattr(settings, "browser_headless", False))
+ chrome._headless = bool(getattr(settings, "browser_headless", True))
chrome._override_user_agent = provider == "testing"
cli = BrowserUseCli(
diff --git a/server/tests/nodes/browser/test_browser_runtime_units.py b/server/tests/nodes/browser/test_browser_runtime_units.py
index 19c7fe57..c762dadf 100644
--- a/server/tests/nodes/browser/test_browser_runtime_units.py
+++ b/server/tests/nodes/browser/test_browser_runtime_units.py
@@ -56,7 +56,7 @@ def test_a_script_error_is_reported_not_raised():
def test_chrome_flags(tmp_path):
argv = build_chrome_argv(Path("chrome"), user_data_dir=tmp_path, proxy_port=4000, major=154, no_sandbox=False, small_shm=False, platform="linux")
- assert "--headless=new" not in argv and "--remote-debugging-port=0" in argv
+ assert "--headless=new" in argv and "--remote-debugging-port=0" in argv
assert "--proxy-server=http://127.0.0.1:4000" in argv and "--proxy-bypass-list=<-loopback>" in argv
assert "--password-store=basic" not in argv and "--no-sandbox" not in argv
assert not any(a.startswith("--user-agent=") for a in argv)
@@ -83,7 +83,8 @@ async def test_visible_browser_requires_linux_display(monkeypatch, tmp_path):
monkeypatch.setattr("nodes.browser._chrome.sys.platform", "linux")
monkeypatch.delenv("DISPLAY", raising=False)
monkeypatch.delenv("WAYLAND_DISPLAY", raising=False)
- chrome = ChromeProcess(profile_id="test", exe=Path("chrome"), profile_root=tmp_path, user_data_dir=tmp_path / "profile", proxy_port=1, major=154, no_sandbox=False, small_shm=False)
+ chrome = ChromeProcess(profile_id="test", exe=Path("chrome"), profile_root=tmp_path, user_data_dir=tmp_path / "profile", proxy_port=1, major=154, no_sandbox=False, small_shm=False, headless=False)
+ assert "--headless=new" not in chrome.argv()
with pytest.raises(NodeUserError, match="BROWSER_HEADLESS=true"):
await chrome.launch()
diff --git a/server/tests/nodes/browser/test_system_browser.py b/server/tests/nodes/browser/test_system_browser.py
index 9cb440ba..d9b71483 100644
--- a/server/tests/nodes/browser/test_system_browser.py
+++ b/server/tests/nodes/browser/test_system_browser.py
@@ -222,7 +222,7 @@ async def test_start_records_connected_version_and_passes_actual_major(monkeypat
running = await runtime._start(profile)
await asyncio.sleep(0)
assert constructor.call_args.kwargs["major"] == 151
- assert constructor.call_args.kwargs["headless"] is False
+ assert constructor.call_args.kwargs["headless"] is True
assert constructor.call_args.kwargs["override_user_agent"] is False
assert running.full_version == "152.1.2.3"
assert running.profile.chrome_major == 152