Metadata-Version: 2.4
Name: tilion
Version: 0.1.0
Summary: Open stealth-browser framework — drive a real recompiled-Chromium (Fortress) that defeats bot-detection fingerprint suites. Drop-in stealth for browser-use, Playwright, Crawl4AI, with an MCP server for AI agents.
Author-email: Tilion <hello@tilion.dev>
License-Expression: LicenseRef-Tilion-Proprietary
License-File: LICENSE
Keywords: agent,anti-bot,bot-detection,browser-automation,browser-use,captcha,cdp,cloudflare,crawl4ai,datadome,mcp,playwright,stealth-browser,undetected,web-scraping
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: python-xlib>=0.33; sys_platform == 'linux'
Requires-Dist: tilion-fortress>=151
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: openai>=1.50; extra == 'all'
Requires-Dist: parsel>=1.8; extra == 'all'
Requires-Dist: pdf2image; extra == 'all'
Requires-Dist: pdfminer-six; extra == 'all'
Requires-Dist: psutil>=5.9; extra == 'all'
Requires-Dist: pytesseract; extra == 'all'
Requires-Dist: scrapy>=2.8; extra == 'all'
Provides-Extra: compat
Requires-Dist: parsel>=1.8; extra == 'compat'
Requires-Dist: scrapy>=2.8; extra == 'compat'
Provides-Extra: dev
Requires-Dist: psutil>=5.9; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: fleet
Requires-Dist: redis>=5; extra == 'fleet'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: ocr
Requires-Dist: pdf2image; extra == 'ocr'
Requires-Dist: pdfminer-six; extra == 'ocr'
Requires-Dist: pytesseract; extra == 'ocr'
Provides-Extra: playwright
Provides-Extra: scrapy
Requires-Dist: parsel>=1.8; extra == 'scrapy'
Requires-Dist: scrapy>=2.8; extra == 'scrapy'
Provides-Extra: selenium
Provides-Extra: server
Requires-Dist: aiohttp>=3.9; extra == 'server'
Requires-Dist: fastapi>=0.110; extra == 'server'
Requires-Dist: psutil>=5.9; extra == 'server'
Requires-Dist: redis>=5; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'server'
Provides-Extra: vision
Requires-Dist: anthropic>=0.40; extra == 'vision'
Requires-Dist: openai>=1.50; extra == 'vision'
Provides-Extra: vision-full
Requires-Dist: anthropic>=0.40; extra == 'vision-full'
Requires-Dist: google-generativeai>=0.8; extra == 'vision-full'
Requires-Dist: openai>=1.50; extra == 'vision-full'
Description-Content-Type: text/markdown

# Tilion

> **A stealth browser for AI agents.** `pip install tilion` — drive a real, undetected Chromium that gets past Cloudflare, DataDome, and bot detection, with no server, no account, and no API key.

**Framework & MCP: Beta** · runs **local & free** · **Tilion Cloud (residential egress) coming soon** · 📖 [Full documentation](DOCUMENTATION.md) · 📊 [Benchmarks](DOCUMENTATION.md#8-benchmarks)

![Same site, same prompt: a vanilla browser is blocked by PerimeterX while Claude + the Tilion MCP returns clean JSON](demo/demo.gif)

> *Real, dated run: [stockx.com](https://stockx.com/nike-dunk-low-retro-white-black-2021) (PerimeterX). A stock browser gets **HTTP 403 — "Access denied"**; Claude with the Tilion MCP returns clean JSON. Reproduce: `python demo/make_split_demo.py`.*

Tilion is an open stealth-browser framework. It runs a recompiled-Chromium stealth engine (**Fortress**) locally, in-process, and gives you one clean API for fetching protected pages, extracting content, crawling sites, reconnaissance, and multi-step automation — plus a **Model Context Protocol (MCP) server** so AI agents can reach for it the moment they get blocked.

```bash
pip install tilion
```

## Quickstart

```python
import asyncio
from tilion import Tilion

async def main():
    async with Tilion() as t:                     # boots the Fortress stealth engine locally
        page = await t.fetch("https://protected.example")   # past Cloudflare/DataDome/403
        print(page["title"], page["text"][:200])

        data = await t.extract("https://site/pricing")       # clean markdown + tables
        docs = await t.crawl("https://site", depth=2)        # whole-site crawl (auto-SPA)
        apis = await t.recon("https://site")                 # discover the site's private API
        hits = await t.search("undetected playwright")       # real-browser web search

asyncio.run(main())
```

No `uvicorn`, no Redis, no auth — local mode holds one real browser and drives it directly.

## Drop-in stealth for your existing stack

Already using **browser-use**, **Playwright**, **Puppeteer**, **Crawl4AI**, or **Stagehand**? They all connect to a browser by CDP URL. Point that at Tilion's Fortress engine and your existing code runs through the stealth browser — one line, no rewrite:

```python
from tilion import Tilion

t = await Tilion().start()
cdp_url = t.cdp_url            # hand this to any CDP-speaking stack

# browser-use:
from browser_use import Agent, BrowserSession
agent = Agent(task="...", browser_session=BrowserSession(cdp_url=cdp_url))

# Playwright:
browser = await playwright.chromium.connect_over_cdp(cdp_url)
```

## MCP server — stealth browsing for any AI agent

Ship the [Fortress MCP server](tilion/mcp/README.md) so a coding/browsing agent auto-selects it when a fetch is blocked:

```bash
pip install "tilion[mcp]"
tilion-mcp          # or: python -m tilion.mcp
```

**Claude Desktop / Cursor** — add to your MCP config:
```json
{ "mcpServers": { "fortress": { "command": "tilion-mcp" } } }
```

26 intent-loaded tools including: `fetch_protected_page`, `extract_page`, `crawl_site`, `recon_site_apis`, `search_web`, `run_browser_task`, `screenshot_page`, `save_page`, `list_browser_tasks`, `get_stealth_cdp_endpoint`. Pre-warmed on startup (~100 ms first call), concurrency-safe, timeout- and SSRF-guarded.

## What you get

| | |
|---|---|
| **`fetch`** | stealth GET past Cloudflare/DataDome/403 + auto challenge-resolve |
| **`extract`** | page → clean markdown + tables + metadata (or a schema-shaped record) |
| **`crawl` / `spa_crawl`** | whole-site crawl, auto-handles SPA/JS + lazy-load → sitemap |
| **`recon`** | reverse-engineer a site's private XHR/JSON API (secret-scrubbed) |
| **`search`** | real-browser web search (no SERP API) |
| **`agent`** | 20 multi-step flows: login, paginate, infinite-scroll, checkout, downloads… |
| **`screenshot` / `save`** | PNG, or export as PDF / HTML / text |
| **`cdp_url`** | raw CDP endpoint for browser-use / Playwright / Puppeteer |
| **`t.page(url)`** | escape hatch to the full DOM API (click, type, wait, evaluate, …) |

## How stealth works

The engine is a **recompiled Chromium C++ fork**, not a JS patch or a stealth plugin. Persona, User-Agent, WebGL, and canvas fingerprints are applied natively with genuine binding returns (`toString() === [native code]`), so there are no JavaScript injection tells. In independent fingerprint suites it runs **Sannysoft-clean, CreepJS 0% headless, browserscan "no bots."**

> **Honest note:** a great fingerprint on a datacenter IP still gets blocked by the biggest sites — real anti-bot decisions weigh the egress IP heavily. For production scraping of hostile targets, add a residential proxy (Tilion's proxy layer is pluggable) or use hosted Tilion cloud egress. Tilion does not claim to be "undetectable."

## Install options

```bash
pip install tilion              # core: stealth browser + fetch/extract/crawl/recon/search
pip install "tilion[mcp]"       # + the MCP server
pip install "tilion[vision]"    # + LLM-driven agent (Claude/OpenAI/Gemini)
pip install "tilion[server]"    # + the multi-tenant control-plane API (self-host cloud)
```

## License

Open-core. The **funnel** — `tilion.facade` + `tilion.mcp` — is BSD-3-Clause. The **engine** (`tilion.core` driver + the Fortress C++ binary via `tilion-fortress`) is proprietary, shipped as bytecode/binary. See OPENSOURCE_SPLIT.md.
