Browser Management with managed_browser Config in Pi-Computer-Use: Helium vs Chrome Guide

The managed_browser configuration option in Pi-Computer-Use controls whether the model launches a full Chrome/Chromium instance or the lightweight Helium wrapper, with precedence given to environment variables over project config files.

Pi-Computer-Use is an open-source framework that enables AI models to control web browsers on the host machine. The managed_browser setting determines which browser implementation handles automation tasks during computer-use sessions. This configuration can be set via environment variables or JSON config files, giving developers flexibility across different deployment environments.

Understanding the managed_browser Configuration Option

The managed_browser option accepts two string values: "chrome" for full Chromium-based browsers or "helium" for the lightweight automation wrapper. The system reads this value from three sources in strict order of precedence.

Configuration Sources and Precedence

Settings are loaded by src/config.ts in the following priority:

1. Environment Variable – PI_COMPUTER_USE_MANAGED_BROWSER overrides all other settings. Set this to helium or chrome for per-run experiments or CI pipelines.
2. Project Configuration – .pi/computer-use.json in the project root, or globally at ~/.pi/agent/extensions/pi-computer-use.json. These override defaults but yield to the environment variable.
3. Built-in Default – Falls back to "chrome" if no other value is supplied.

The loadComputerUseConfig function in src/config.ts normalizes the raw JSON input and verifies that the supplied value is either "helium" or "chrome". Invalid values are rejected during the loading phase. The active configuration is exposed via getComputerUseConfig(), which returns an object containing the validated managed_browser property.

Validation and Normalization

When loadComputerUseConfig processes the configuration, it validates the managed_browser field against the allowed enum values. The resulting configuration object stores the normalized value in activeConfig, making it available to the bridge layer without additional parsing overhead.

Helium vs Chrome: Implementation Differences

When a model invokes the launch_browser action, the bridge code in src/bridge.ts (around line 2046) retrieves the current setting via getComputerUseConfig().managed_browser. The selected implementation determines how the browser process is spawned and managed.

Chrome Path

Setting managed_browser to "chrome" launches a standard Chromium-based process (Chrome, Chromium, or Edge). The bridge optionally passes --remote-debugging-port if the PI_COMPUTER_USE_CDP_PORT environment variable is set. This path creates a regular desktop window with full browser features, supporting extensions and specific user profiles.

Use this option when you need full browser functionality, extension support, or when testing requires a specific Chrome installation.

Helium Path

Setting managed_browser to "helium" spawns the Helium browser, a headless-friendly wrapper around Chrome that offers a minimal UI for automation. Helium automatically opens a remote debugging port, enabling Chrome DevTools Protocol (CDP) integration without additional flags. The reduced UI surface keeps the cursor overlay less intrusive, making it ideal for headless environments or when screen real estate is limited.

Chrome DevTools Protocol (CDP) Support

Both implementations support CDP for deep browser automation, but their initialization differs:

• Chrome: Requires explicit --remote-debugging-port configuration via PI_COMPUTER_USE_CDP_PORT
• Helium: Automatically enables the debugging port, providing out-of-the-box CDP connectivity

Regardless of the underlying binary, the model interacts with identical high-level actions: launch_browser, navigate_browser, and evaluate_browser. Both return a standardized browser-page state that the runtime observes and controls.

How the Bridge Selects the Browser Implementation

The selection logic resides in src/bridge.ts. When processing a launch_browser call, the bridge:

1. Retrieves the active configuration using getComputerUseConfig()
2. Checks the managed_browser property
3. Spawns the appropriate process binary with environment-specific arguments
4. Establishes the CDP connection if configured
5. Returns the browser handle to the model

This abstraction ensures that switching between Chrome and Helium requires no changes to model prompts or action schemas—only the configuration value changes.

Configuring managed_browser in Practice

Force Helium for a single execution by setting the environment variable before loading the configuration:

// Force Helium via environment variable
process.env.PI_COMPUTER_USE_MANAGED_BROWSER = "helium";
import { loadComputerUseConfig } from "./config";

// Reload configuration with the new environment override
loadComputerUseConfig(process.cwd());
// Subsequent launch_browser calls will start Helium

Inspect the current configuration at runtime:

import { getComputerUseConfig } from "./config";

const cfg = getComputerUseConfig();
console.log(`Managed browser in use: ${cfg.managed_browser}`);
// Output: "Managed browser in use: helium" or "chrome"

Launch a browser from an action context:

import { launch_browser } from "./actions";

await launch_browser({ url: "https://example.com" });
// Bridge automatically selects Chrome or Helium based on config

Summary

• The managed_browser option in Pi-Computer-Use selects between "chrome" (full Chromium) and "helium" (lightweight wrapper)
• Configuration precedence: Environment variable (PI_COMPUTER_USE_MANAGED_BROWSER) > Project config (.pi/computer-use.json) > Default ("chrome")
• src/config.ts handles validation via loadComputerUseConfig and exposes settings via getComputerUseConfig()
• src/bridge.ts implements the selection logic around line 2046 when processing launch_browser actions
• Helium automatically enables CDP ports, while Chrome requires explicit PI_COMPUTER_USE_CDP_PORT configuration
• Both implementations present identical APIs to the model, ensuring seamless switching between headless and full-browser environments

Frequently Asked Questions

How do I switch between Helium and Chrome without modifying code?

Set the PI_COMPUTER_USE_MANAGED_BROWSER environment variable to "helium" or "chrome" before starting your Pi-Computer-Use session. This overrides any project configuration files and persists only for the current process lifetime, making it ideal for CI/CD pipelines or temporary testing.

Where does Pi-Computer-Use store its browser configuration?

The framework checks .pi/computer-use.json in your project root first, then falls back to ~/.pi/agent/extensions/pi-computer-use.json for global settings. If neither file exists or the key is missing, it defaults to "chrome". The src/config.ts module handles this resolution chain during initialization.

Does Helium support the same Chrome extensions as regular Chrome?

No. While Helium wraps Chrome's rendering engine, it presents a minimal UI specifically designed for automation. If your workflow requires specific Chrome extensions, user profiles, or full browser chrome, configure managed_browser as "chrome" rather than "helium".

Can I use Chrome DevTools Protocol with both browser options?

Yes. Both implementations support CDP, but Helium enables the remote debugging port automatically, whereas Chrome requires you to set the PI_COMPUTER_USE_CDP_PORT environment variable to specify the port number. Ensure your CDP client connects to the same port configured during browser launch.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}