From b3fc87a2f58cce0ac8091e891c7bdf763ccfa66a Mon Sep 17 00:00:00 2001 From: EugeneTes Date: Wed, 23 Sep 2026 19:40:58 +0000 Subject: [PATCH] Document Fortress stealth-browser tools --- .env.example | 14 ++++++++++++++ README.md | 18 ++++++++++++++++++ SETUP-WINDOWS.md | 4 ++++ 3 files changed, 36 insertions(+) diff --git a/.env.example b/.env.example index f36caf2..0e5e93e 100644 --- a/.env.example +++ b/.env.example @@ -36,3 +36,17 @@ PLAYWRIGHT_BROWSER= # PLAYWRIGHT_EXTRA_ARGS: shell-style extra flags for @playwright/mcp, e.g. # PLAYWRIGHT_EXTRA_ARGS=--device "iPhone 15" --isolated PLAYWRIGHT_EXTRA_ARGS= + +# Fortress stealth-browser tools (MCP bridge). When FORTRESS_ENABLED=true the +# agent gets ~30 fortress_* tools (read/extract pages as markdown, fetch pages +# behind Cloudflare/DataDome, web search, crawl, screenshots, saved logins). +# The Docker image ships it; on a bare host run: pip install "tilion[mcp]" "mcp<2" +FORTRESS_ENABLED= +# FORTRESS_COMMAND: how to start the server. Default tilion-mcp; if that isn't +# on PATH (common on Windows) use: python -m tilion.mcp +FORTRESS_COMMAND= +FORTRESS_HEADLESS=true +# Optional: residential proxy, region hint, captcha solver key. +TILION_PROXY= +TILION_REGION= +CAPTCHA_API_KEY= diff --git a/README.md b/README.md index 772fc73..4d14092 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,14 @@ The bot can read and write the owner's Google Calendar. Setup is one-time in Goo The refresh token is stored at `workspace/.secretary/google-token.json`. Delete that file to disconnect; run `/connect_calendar` again to relink. +## Stealth browsing (Fortress) + +[Fortress](https://github.com/tiliondev/fortress) is a Chromium build that corrects the browser fingerprint inside the engine, so pages behind Cloudflare, DataDome, PerimeterX, or Akamai load instead of returning 403 or a challenge. With `FORTRESS_ENABLED=true` the bot starts its MCP server (`tilion-mcp`) and the agent gets about 30 `fortress_*` tools: `read_page` and `extract_page` (clean markdown, far fewer tokens than raw HTML), `fetch_protected_page`, `search_web`, `crawl_site`, `screenshot_page`, `save_profile` / `load_profile` for keeping logins, and more. It sits next to the Playwright tools; the agent is told to reach for Fortress when reading the web or when a site blocks it. + +The Docker image ships it ready to use. On a bare host, install it once with `pip install "tilion[mcp]" "mcp<2"` (the pin works around tilion not supporting the 2.x MCP library yet); the engine, about 200 MB, downloads on first use. Linux x64 and Windows x64 only. + +Screenshots, saved pages, downloads, and saved profiles land in `workspace/fortress/`, so the agent can send them back with `send`. If Fortress fails to start, the bot logs the error and runs without it. Set `LOG_LEVEL=debug` to see the server's own output. + ## Workspace ``` @@ -57,6 +65,7 @@ workspace/ MEMORY.md facts the assistant keeps; it edits this itself scripts/ scripts for scheduled jobs inbox/ files you sent + fortress/ files written by the Fortress tools .secretary/ runtime state ``` @@ -80,6 +89,13 @@ The agent's edits to `MEMORY.md` are local runtime data. Leave them uncommitted, | `PLAYWRIGHT_HEADLESS` | no | `true` | Run browser headless. `false` opens a visible window | | `PLAYWRIGHT_BROWSER` | no | `chrome` | `chrome`, `firefox`, `webkit`, or `msedge` | | `PLAYWRIGHT_EXTRA_ARGS` | no | | Extra flags passed to `@playwright/mcp` (shell-quoted) | +| `FORTRESS_ENABLED` | no | `false` | Enable the Fortress stealth-browser MCP bridge (`fortress_*` tools) | +| `FORTRESS_COMMAND` | no | `tilion-mcp` | Command that starts the Fortress MCP server (shell-quoted), e.g. `python -m tilion.mcp` | +| `FORTRESS_HEADLESS` | no | `true` | `false` opens a visible Fortress window (native hosts only) | +| `FORTRESS_CHANNEL` | no | `latest` | Fortress engine channel. `stable` currently fails to launch (upstream bundle naming bug) | +| `TILION_PROXY` | no | | Egress proxy for Fortress, `http://user:pass@host:port`. A residential proxy is the main lever on hard targets | +| `TILION_REGION` | no | | Region hint for Fortress, e.g. `us`, so timezone and locale match the proxy IP | +| `CAPTCHA_API_KEY` | no | | Captcha solver key; enables `fortress_solve_captcha` and auto-solve during fetch | | `GOOGLE_CLIENT_ID` | no | | OAuth client id (TVs and Limited Input devices) — enables the calendar tool | | `GOOGLE_CLIENT_SECRET` | no | | OAuth client secret — required alongside `GOOGLE_CLIENT_ID` | | `GOOGLE_REFRESH_TOKEN` | no | | Deprecated. If set, seeded once into `workspace/.secretary/google-token.json`, then ignored. | @@ -121,3 +137,5 @@ Run `npm run dev` with a real bot and walk through every line: 19. Reply to one of the bot's earlier messages with a follow-up like "what did you mean by that?" → the answer references that specific message, not the most recent one. Then "reply with quote" a specific phrase from a bot message → the answer references the quoted phrase. 20. Forward a voice message from another chat and add a text comment. The bot should reply once, referencing both your comment and what the voice said, not twice with each in isolation. 21. Delete `workspace/.secretary/google-token.json` if it exists. Ask "what's on my calendar tomorrow?" → tool replies with a "not connected" message referencing `/connect_calendar`. Run `/connect_calendar` → bot replies with a `https://google.com/device` URL and a short code. Approve on that page, then `/calendar_done` → bot replies `✅ Calendar connected.` and the token file now exists. Ask the same calendar question again → the tool answers. +22. Start with `FORTRESS_ENABLED=true`. Startup log shows `fortress tools enabled (N tools)` with N around 30. Ask "read https://quotes.toscrape.com/js/ and give me the first three quotes" → the quotes come back (that page is empty without JavaScript). +23. With Fortress enabled, ask "take a Fortress screenshot of https://example.com and send it" → an image attachment arrives and `workspace/fortress/` has the PNG. diff --git a/SETUP-WINDOWS.md b/SETUP-WINDOWS.md index 1eca1d0..2461f39 100644 --- a/SETUP-WINDOWS.md +++ b/SETUP-WINDOWS.md @@ -51,6 +51,8 @@ No quotes, no spaces around `=`. | `SECRETARY_SHELL=` | Full path to `bash.exe` if Git is not installed at `C:\Program Files\Git`. | | `WORKSPACE_DIR=./workspace` | Where the assistant keeps its memory file, scripts, and files you send. | | `LOG_LEVEL=info` | Set to `debug` to see more in the console. | +| `FORTRESS_ENABLED=` | Set to `true` to give the assistant the Fortress stealth browser, for reading pages that block normal browsers. Needs Python: open a terminal and run `pip install "tilion[mcp]" "mcp<2"` once. The browser engine (about 200 MB) downloads the first time it is used. | +| `FORTRESS_COMMAND=` | Leave empty. If the console says `fortress bridge failed to start` with `ENOENT`, set it to `python -m tilion.mcp`. | 4. Save the file and close Notepad. @@ -120,6 +122,8 @@ Alternatively, Windows Task Scheduler can start `run.bat` at logon, but any star | Voice notes reply "Voice transcription is not configured" | No OpenAI key | Add `OPENAI_API_KEY` to `.env` and restart | | A scheduled script fails with `failed to start bash` | Git for Windows is not at the default path | Set `SECRETARY_SHELL` to the full path of `bash.exe` | | Replies arrive as raw text with `` tags | Telegram rejected the formatting, the bot fell back to plain text | Harmless; report the message content if it repeats | +| `fortress bridge failed to start` with `ENOENT` | `tilion-mcp` is not on PATH | Set `FORTRESS_COMMAND=python -m tilion.mcp` in `.env` | +| `fortress bridge failed to start` with `ModuleNotFoundError: No module named 'mcp.server.fastmcp'` | pip installed the 2.x MCP library, which Fortress doesn't support yet | Run `pip install "mcp<2"` | | The window closes before you can read anything | An error happened before the launcher's pause | Open a terminal in the folder and run `.\run.bat` from there | If the console shows a message not in this table, start the bot with `LOG_LEVEL=debug` in `.env` and read the last few lines before the exit.