chromiumfish (Python)

Stealth Chromium with a drop-in Playwright harness.

pip install chromiumfish
chromiumfish fetch        # download + cache the browser build

Usage

Sync

from chromiumfish.sync_api import Chromiumfish

with Chromiumfish(persona_seed="alpha-7", headless=True) as browser:
    page = browser.new_page()
    page.goto("https://example.com")
    page.screenshot(path="fp.png")

Async

import asyncio
from chromiumfish.async_api import AsyncChromiumfish

async def main():
    async with AsyncChromiumfish(persona_seed="alpha-7") as browser:
        page = await browser.new_page()
        await page.goto("https://example.com")
        print(await page.title())

asyncio.run(main())

The returned object is a standard Playwright Browser, so new_context, new_page, routing, tracing, etc. all work as usual.

Options

IP-to-Timezone

timezone="auto" aligns the browser clock with the egress IP (handy behind a proxy). It uses a compact ip2tz database downloaded once and cached; you can also query it directly:

from chromiumfish import lookup_timezone, resolve_timezone

lookup_timezone("8.8.8.8")                 # -> "America/Los_Angeles"
resolve_timezone(proxy="http://user:pass@host:port")   # egress IP -> timezone

The DB auto-updates: it tracks the latest monthly build (cached, re-checked weekly), so you get fresh data without upgrading the SDK. Pin a fixed version with CHROMIUMFISH_GEOIP_VERSION=2026.06 for reproducibility.

AI agent

ChromiumFish ships a native in-browser agent (perceive → think → act, driven by an OpenAI-compatible LLM). launch_agent starts the browser with the agent layer and connects over CDP; run_task drives it from a plain-language goal.

from chromiumfish import launch_agent

# LLM config: a nearby .env (OPENAI_API_*), or pass api_key=/api_base=/model= to launch_agent
with launch_agent(typing="human") as agent:   # typing: "human" (default) / "fast" / "instant"
    r = agent.run_task("Search DuckDuckGo for 'chromiumfish' and give me the first result's URL.")
    print(r.final_text)

run_task returns an AgentResult (success, final_text, steps, summary()); pass a prior run's steps back as plan= to replay a flow deterministically. Install the agent extra (pip install "chromiumfish[agent]") for the websocket-client dependency. Point at a local build with CHROME_BIN=…/ChromiumFish. Full guide: chromiumfish.com/ai-agent.

External agents

Prefer a third-party framework (Hermes, OpenClaw, browser-use, Playwright, …)? chromiumfish serve exposes a plain CDP endpoint — with your persona/proxy/timezone active — for any of them to attach to:

chromiumfish serve --persona-seed alice            # -> http://127.0.0.1:9222
# e.g. Hermes ~/.hermes/config.yaml: browser: { cdp_url: "http://127.0.0.1:9222" }

Full guide: chromiumfish.com/agents.

CLI

chromiumfish fetch [--browser-version X] [--force]   # download + cache
chromiumfish path                                     # print binary path
chromiumfish serve [--port 9222] [--persona-seed S]  # CDP endpoint for external agents
                   [--proxy URL] [--window-size WxH] [--timezone Z] [--headless]
                   [--browser-version X] [--extra-args ARGS] [--timeout S]
chromiumfish clear                                    # wipe the cache
chromiumfish --version

Builds are cached under ~/.cache/chromiumfish/<version>/ (override with CHROMIUMFISH_CACHE_DIR). Pin a build with CHROMIUMFISH_VERSION.

Attribution

IP Geolocation by DB-IP — the ip2tz timezone database is derived from DB-IP City Lite, used under CC BY 4.0.

License

MIT © Arman Hossain. See the repository.