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

> Master browser management with managed_browser config in Pi-Computer-Use. Learn the Helium vs Chrome differences and optimize your Pi computer setup for efficient browsing.

- Repository: [injaneity/pi-computer-use](https://github.com/injaneity/pi-computer-use)
- Tags: how-to-guide
- Published: 2026-07-16

---

**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`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/.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`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/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:

```typescript
// 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:

```typescript
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:

```typescript
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`](https://github.com/injaneity/pi-computer-use/blob/main/.pi/computer-use.json)) > Default (`"chrome"`)
- [`src/config.ts`](https://github.com/injaneity/pi-computer-use/blob/main/src/config.ts) handles validation via `loadComputerUseConfig` and exposes settings via `getComputerUseConfig()`
- [`src/bridge.ts`](https://github.com/injaneity/pi-computer-use/blob/main/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`](https://github.com/injaneity/pi-computer-use/blob/main/.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`](https://github.com/injaneity/pi-computer-use/blob/main/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.