agent-browser

agent-browser — browser automation over HTTP

Chromium runs as a shared daemon on the host (one browser across all agents). You drive it by POST'ing to /agent-api/browser with the CLI verb + args. Response is {exitCode, stdout, stderr} as JSON.

The shell you're in

Hermes agents (Nova, Ada, …): your container has python3 but not curl. Use python3 for every HTTP call below.

OpenClaw agents (Max, …): your container has both curl and python3. Either works; curl is shorter.

Python helper (works everywhere)

Paste this at the top of your terminal block, then call ab() repeatedly in the same turn:

import json, os, urllib.request
API = os.environ.get("CC_API_BASE", "http://localhost:3300/api")
TOKEN = os.environ["CC_BOT_TOKEN"]
def ab(cmd, args=None, stdin=None):
    body = json.dumps({"cmd": cmd, "args": args or [], "stdin": stdin}).encode()
    req = urllib.request.Request(
        f"{API}/agent-api/browser",
        data=body,
        headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=50) as r:
        return json.loads(r.read())

Recipes

Read the visible text of a page (most common — research/citations):

ab("open", ["https://example.com"])
print(ab("get text", ["body"])["stdout"])
ab("close")

Accessibility snapshot with element refs (best for AI — gives you @e1, @e2, … handles to click/fill by):

print(ab("snapshot")["stdout"])

Click an element by ref from a snapshot:

ab("click", ["@e3"])

Find + act by semantic locator (resilient to page redesigns):

ab("find role", ["button", "click", "--name", "Submit"])
ab("find text", ["Sign In", "click"])
ab("find label", ["Email", "fill", "[email protected]"])

Evaluate JavaScript on the current page:

print(ab("eval", ["document.title"])["stdout"])

Open → snapshot → extract → close in one turn (preferred):