Your browser

Use it for sites you are signed in to and pages on your local network. Python only: the SDK or the holo CLI. The environment is {"kind": "web", "host": "user_device"}.

Run a session

Install

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

Create an agent whose environment sets host to user_device, then run a session with it. In Python there is nothing else to set up. From the CLI, serve your browser and point the agent at the session_id it prints (the CLI example uses the agent the Python example creates). All flags: holo local.

from hai_agents import Client

client = Client()

agent = client.agents.create_agent(
    name="local-web",
    description="Drives a browser on my own machine.",
    environments=[{"id": "my-laptop", "kind": "web", "host": "user_device"}],
)

result = client.run_session(
    agent=agent,
    messages="Open news.ycombinator.com and summarize the top story",
)
print(result.status, result.answer)

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

# In another terminal, route the agent's browser environment here.
holo run "Open news.ycombinator.com and summarize the top story" \
  --agent local-web \
  -o 'agent.environments[kind=web].session_id=<printed id>'

The Chrome it drives

The SDK attaches to a Chrome 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 once and the agent finds you signed in next time. The SDK never touches your everyday Chrome profile (Chrome does not allow remote debugging on it). To drive a different Chrome, start it yourself before the session. Chrome only opens the debugging port with --user-data-dir, so pick a dedicated directory and keep it for the logins you want the agent to have.

/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"

Behavior and limits

When a session starts, the SDK opens a connection inside your Python process. It receives the agent’s actions, carries them out in your browser, and ties the session to this machine. Observe and steer, changes, and Agent View work as for a cloud run.

One at a time. A Python process drives one local browser at a time. A new session on it takes it over and cancels the earlier session.
Tied to your process. The connection closes when your Python process exits, and the sessions it served are cancelled (Chrome stays open). If the connection drops mid-session, the session is cancelled too.
Cloud-only fields. Vaults, browser profiles, and proxies apply to cloud browsers only. Your Chrome’s own logins and network fill that role.

Auto-connect scope

You start the session with	Connection
An agent spec or object passed to `run_session`, `start_session`, or `create_session`	The SDK connects your machine for you.
A registered agent referenced by name, or from the web app or another machine	Serve the browser with `holo local browser`, then set the printed `session_id` on the `user_device` environment (see the CLI example above).
`HAI_AUTO_BRIDGE=0` set	Auto-connect is off. Serve the browser yourself, as above.

Build an agent

Environments

Run sessions

Tools and integrations

Production

Run a session

The Chrome it drives

Behavior and limits

Auto-connect scope

​Run a session

​The Chrome it drives

​Behavior and limits

​Auto-connect scope

Run a session

The Chrome it drives

Behavior and limits

Auto-connect scope