Skip to main content
With local browser control, the agent drives Chrome on your own machine instead of a browser H hosts in the cloud, keeping the same agent and session lifecycle you already use. Run a session that uses a local browser from the hai-agents Python SDK (the only SDK with local control today) and it launches Chrome and connects it to H for you. Use it when the work has to happen where you are: a site you are signed in to on your machine, or anything behind your local network that a cloud browser cannot reach.
The agent acts in a real Chrome on your machine: it can browse, run page scripts, and read that browser’s cookies and storage. Run it only for tasks you would do yourself. Stop a run at any time by cancelling the session.

​
How it works

A local browser is a normal browser environment with its host set to user_device. When a session starts with one, the SDK opens a connection inside your Python process. The connection receives the agent’s actions and carries them out in the Chrome it controls, and it is what ties this particular session to this particular machine. Everything else is unchanged: observe and steer the run and read its answer just as you would a remote one. A Python process drives one local browser at a time. Starting a new session that uses the local browser while an earlier one is still running hands the browser to the new session and cancels the earlier one. Because it drives your machine, a local browser skips the cloud-provisioning fields: vaults and browser profiles apply to cloud-hosted browsers only. Your local Chrome’s own logins and cookies fill that role.
1

Install the browser driver

The browser driver is an optional extra, provided by the hai-drivers package:
Install
pip install "hai-agents[browser]"
2

Run a session

In Python, define the environment inline on the agent and run a session. There is nothing else to set up; the SDK starts Chrome if needed and drives it there. From the CLI, serve the browser with hai local browser and point the agent at the session_id it prints.
from hai_agents import Client

client = Client()  # reads HAI_API_KEY from the environment

result = client.run_session(
    agent={
        "name": "local-web",
        "description": "Drives a browser on my own machine.",
        "environments": [
            {
                "id": "my-laptop",
                "kind": "web",
                "host": "user_device",
            }
        ],
    },
    messages="Open news.ycombinator.com and summarize the top story",
)
print(result.status, result.answer)

pip install "hai-agents[cli,browser]"

# Serve the browser and leave it running; it prints the session_id it serves.
hai local browser

# From another terminal, route a registered agent's browser environment here.
hai run "Open news.ycombinator.com and summarize the top story" \
  --agent my-web-agent \
  -o 'agent.environments[kind=web].session_id=<printed id>'
The session behaves like any other: observe and steer it, read changes, or watch it in Agent View. The Python connection closes when your process exits; Chrome stays open.Auto-connect covers agents defined inline in run_session, start_session, or create_session. A registered agent referenced by name, or a session started from the web app or another machine, expects its user_device environment to carry the session_id of a machine served with hai local browser, as in the CLI tab. Set HAI_AUTO_BRIDGE=0 to opt out of auto-connect entirely.

​
The Chrome it drives

The SDK attaches to a Chrome instance with remote debugging open on port 9222. If none is running, it launches one with its own profile in ~/.hai/chrome-profile. That profile persists across runs: sign in to a site once and the agent finds you signed in next time. Your everyday Chrome profile is never touched; Chrome does not allow remote debugging on it. To drive a different Chrome, start it yourself before the session and the SDK attaches to it instead: 
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --user-data-dir="$HOME/chrome-for-agents"

google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/chrome-for-agents"
Chrome only opens the debugging port on a profile passed with --user-data-dir, so pick a dedicated directory and keep it for the logins you want the agent to have.

​
Next steps

Browser configuration

Modes, start URL, profiles, and the rest of the browser environment.

Local desktop

Drive the whole desktop on your machine, not just the browser.

Observe & steer

Watch a local run, redirect it mid-task, and read the answer.

Sessions

The session lifecycle, including how to cancel a run.