awbrowse

A real browser, from an agent, over a service you host.

pip install awbrowse

from awbrowse import BrowseClient

b = BrowseClient("https://browser.example.com", token="...")
page = b.browse("https://example.com")
print(page.ok, page.engine, len(page.text))

awbrowse get https://example.com     # render, print the text
awbrowse shot https://example.com    # -> screenshot.jpg (extension sniffed)
awbrowse --self-test                 # prove the contract, offline

The service origin comes from --url or AWBROWSE_URL, the token from --token or AWBROWSE_TOKEN. Neither is guessed — a client that quietly falls back to some default endpoint is sending your pages somewhere you did not choose.

What this is, and what it is not

It is a client. The rendering engine — headless browsers, session pools, scrape schemas — stays where it is; this is the wire contract, packaged so anything can speak it. Point it at any service exposing the routes below.

That split is deliberate. The alternative was lifting a 1,200-line service with a dozen private imports into a package, which produces something that ModuleNotFoundErrors on your machine while reading as authoritative. A broken package is worse than no package.

Authenticated pages go through a session

browse() cannot take cookies, and that is a feature.

The service's browse model declares extra="forbid". It did not always: with pydantic's default extra="ignore", a request carrying cookies or storage_state had those fields silently dropped, so an "authenticated" render ran anonymous and returned the login page as though it were the app — HTTP 200, correct-looking output, completely wrong answer.

So this client sends exactly the four declared fields and nothing else, and credentials go where the server actually reads them:

with b.open_session(storage_state=...) as s:
    s.fill("#user", "me")                 # value= , not text=
    s.click("#login")
    o = s.observe()                       # url, title, text, ELEMENTS, screenshot
    for el in o.elements:                 # what an agent decides to click from
        print(el["tag"], el["text"], el["selector"])
    for r in s.network(clear=False):      # why a page that "renders fine" is failing
        print(r["status"], r["content_type"], r["url"])

session.network() is the reason to reach for a session while debugging: a page that renders correctly and fails silently is usually failing in a request nobody looked at. Two things make an empty list mean nothing, and both are measured: it is FILTERED (only JSON-ish responses — content-type json, /api/ in the URL, or .json; never a 4xx/5xx and never a preflight), and the default DRAINS the buffer server-side, so a second consecutive call returns nothing.

observe() is a different shape from browse() — it has a title and an elements list that /browse does not send. They are separate types for that reason: parsed as a Page, elements vanishes and an agent picks what to click from a list it never saw.

An action the service does not dispatch is refused here, because it would not be refused there: the server's dispatch is an if/elif chain with no else, so a typo'd action is a no-op that answers 200 — "I clicked and nothing happened". Same for a misspelt open_session field: unlike /browse, that model does not forbid extras, so a mistyped storage_state is dropped in silence and hands you an anonymous session that looks logged in.

What a live probe found that no offline test could

Both of these shipped in the first draft, and both are the failure this package exists to refuse — a request that is valid, a response that is 200, and a key that is simply absent:

The screenshot key is not the screenshot field. The request says screenshot: true; the response says screenshot_base64. Reading the request's name back off the response yields None on every successful capture, so awbrowse shot would have reported "the service returned no screenshot" forever while the service sent one every time.

The capture is JPEG, not PNG. Nothing in the request says so. A default output of screenshot.png writes JPEG bytes under a name that lies about them — fine in a viewer that sniffs, broken in anything that trusts the extension. So the extension is sniffed from the magic bytes, and an -o whose extension disagrees is honoured and mentioned.

Page therefore exposes exactly what the service was measured to send — status, url, engine, content, and screenshot_base64 when asked. No title, no html: this route sends neither, and an attribute that is empty on every response is worse than an absent one, because callers branch on it. Everything else is on .raw.

Two things it refuses to do

Return an empty page on failure. A dead service raises BrowseError. If it returned "", a transport failure and a genuinely blank page would be the same value to every caller, and the outage would look like a boring page.

Send an empty Authorization header. No token means no header at all. An empty Bearer is rejected differently from an absent one, and the difference sends you debugging the auth server instead of your config.

--self-test

Every install can prove the client still holds its contract, with no service and no network:

$ awbrowse --self-test
  PASS  browse body is exactly the declared field set
  PASS  text reads `content`; screenshot reads the MEASURED response key
  PASS  a failed render raises rather than arriving as a blank page
  PASS  network reads the MEASURED key; an undispatched action is refused
  PASS  image format sniffed, not assumed; base_url normalised; no empty Bearer
SELF-TEST: awbrowse ok

It asserts the exact request field set rather than membership — an extra key is a 422 for the whole request, and a test that only checks "url is in there" passes on that bug.

The aw family

Standalone tools that share one idea: replace something you would otherwise have to trust with something you can check.

Each installs on its own, works offline, and needs no account.

awnix is the ground floor — A Linux you can hand to an agent — immutable base, capabilities included.

The Aitherium ecosystem

Every repository here is public. Each publishes an aither-manifest.json beside its page, so any surface can read every sibling's — the network is browsable from any node in it.