Skip to main content

orion-browser

Signed-in browsers your agents can take turns owning.

MIT licensed · Linux + systemd · Persistent profiles · CLI + MCP

One browser. Too many hands.

Two agents share a signed-in browser. One changes the tab while the other fills a form. Focus moves, identity gets mixed up, and the operator has to untangle the work.

orion-browser runs one headful Chrome per configured identity, on an independent virtual screen. Each agent leases a browser, connects its existing driver to the returned DevTools endpoint, renews during long work, and releases when finished. Sign-in state stays in the profile across clean restarts.

Start with two identities

Requires Linux with a systemd user instance, Python 3.11+, Google Chrome stable, TigerVNC, noVNC, websockify, xdotool, and xwd. The guide covers prerequisites and operator sign-in.

Install the tagged source (No PyPI package required):

git clone --branch v0.1.0 https://github.com/OrionArchitekton/orion-browser-oss.git
cd orion-browser-oss
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .

Prepare the pool:

mkdir -p ~/.config/orion-browser
cp config.example.toml ~/.config/orion-browser/config.toml
orion-browser setup

Lease, connect, release (Use the returned endpoint with your CDP driver):

orion-browser --json lease anon --holder agent-42
# Connect your driver to data.endpoint.
# Complete the task, renewing the lease during long work.
orion-browser --json release anon --holder agent-42

Command surface

  • setup: Check host dependencies and prepare owner-only state and profile directories.
  • status: Read browser state, holder, and expiry. It does not hand out an endpoint.
  • lease: Acquire or renew a browser lease and receive its DevTools endpoint.
  • release: Close the session and give back the lease while keeping the profile.
  • view: Open an operator watch view, or request an interactive link as the holder.

The useful boundaries

  • Your driver, a leased browser: Keep agent-browser or Playwright. The pool manages leases and lifecycle; the driver attaches directly over CDP.
  • Profiles persist. Sessions turn over.: A new holder after expiry gets a replacement Chrome session. The old session must be shown gone first. Expiry alone does not stop Chrome.
  • MCP ownership is explicit: One MCP server process is one holder, including its subagents. Parallel workers need different browsers or distinct CLI holders.
  • Coordination on a trusted host: This is not a sandbox or publishing approval layer. Local processes can bypass leases, and signed-in browsers carry real account authority. Read SECURITY.md before use.

Links