Katphi Browser

Katphi Browser is a desktop web browser designed for developers, researchers, and privacy-conscious users. It combines the rendering power of Qt WebEngine (Chromium) with a rich set of built-in tools: a hierarchical bookmark manager, a password manager, a screenshot suite, Tor integration, and an extensible plugin system.

The base browser is free and open source. All core features — including Tor integration, privacy tools, and the built-in plugins (Themes, Split View, Pentesting Suite) — work locally without an account.

Katphi is written entirely in Python 3.10+ and relies on a focused set of dependencies:

Runtime requirements

1. 1
   Get the source code

   Clone or download the project into a folder containing main.py, requirements.txt, and config.yaml.

2. 2
   Create and activate a virtual environment

   A virtual environment isolates Katphi's dependencies from the system Python and avoids the externally-managed-environment error on modern Linux distros.

   # Linux / macOS
   python3 -m venv venv
   source venv/bin/activate
   python -m pip install --upgrade pip setuptools wheel
   
   # Windows (PowerShell / CMD)
   python -m venv venv_win
   venv_win\Scripts\activate.bat

3. 3
   Install PySide6 first, explicitly

   When installing everything from requirements.txt at once, pip can be interrupted by a heavy optional package (e.g. chromadb, sentence-transformers) before it reaches PySide6, leaving the environment without it. Install and verify PySide6 on its own first:

   pip install --upgrade "PySide6>=6.5.0"
   python3 -c "from PySide6.QtWebEngineWidgets import QWebEngineView; print('PySide6 OK')"

   Only PySide6 is supported — PyQt5 and PyQt6 are not recognised by the codebase and must not be installed alongside it.

4. 4
   Install the remaining dependencies

   pip install -r requirements.txt

   On Linux, PySide6 and Qt WebEngine also need native system libraries (libxcb-cursor0, libnss3, libgl1-mesa-glx, and similar) — see INSTALACION.md in the project root for the full per-distro list.

5. 5
   Install Playwright browsers (optional)

   Only needed for the Advanced Scraping plugin's Playwright mode.

   playwright install chromium

6. 6
   Run the browser

   python3 main.py

Verify the connection to the backend

python3 verificar_conexion_backend.py

This checks reachability of the Katphi API server (required for account login, session sync, and plugin distribution).

The navigation toolbar sits at the top of the window. It is compact by design — every element has a purpose.

Responsive layout

The toolbar adapts to the window width. At widths below 950 px, the tab search field is hidden. Below 750 px, the profile switcher is also hidden. Below 600 px, only the essential URL bar, menu button, and account button remain visible.

Katphi uses a custom tab bar built on QTabWidget with a + button that always appears immediately after the last tab. Tabs are movable, closable, and can be searched in real time from the toolbar.

Key capabilities

Per-tab privacy profiles

Each tab can be associated with a different browser profile, which means separate cookies, storage, and network settings. This allows you to be logged into the same site with different accounts simultaneously.

The bookmark system offers a hierarchical folder tree stored in a local SQLite database. It replaces the flat bookmark list common in most browsers with a proper nested folder structure.

Automatic migration

On first launch, if a flat bookmark database from an older version is detected, Katphi automatically migrates it to the new hierarchical format without data loss.

Browsing history is stored locally in SQLite. The History panel (accessible from the nav bar or Ctrl+H) shows a time-sorted list of visited pages with search and delete capabilities.

History is linked to the user's session. When the user is not logged in, history is cleared on browser close for added privacy.

The Download Manager panel (Ctrl+J) shows all active and completed downloads with progress bars, file size information, and open/reveal-in-folder actions.

Downloads are handled by Qt's native download mechanism and stored in the system's default Downloads folder.

Katphi includes a built-in encrypted password manager that stores credentials locally using Fernet symmetric encryption derived from a master password via PBKDF2-HMAC-SHA256.

Press Ctrl+F to open the Find bar. It appears below the nav bar and highlights all matches on the current page. Use Enter / Shift+Enter to cycle through matches, or press Esc to close.

The find system wraps Qt WebEngine's native text search, supporting case-sensitive matching and real-time highlighting as you type.

Katphi ships with a three-mode screenshot suite accessible from the main menu or via keyboard shortcuts.

All screenshots are saved as PNG files. An annotation editor allows you to draw, add text, and highlight areas before saving.

Katphi includes a built-in network interceptor that operates at the Qt WebEngine request level, blocking ads and trackers before they are loaded.

Katphi includes native Tor support via the stem library and a SOCKS5 proxy routed through a local Tor daemon. It follows the same workflow as Tor Browser: the user activates Tor → bootstrap → automatic browser restart with all traffic routed through Tor.

How to use Tor

1. 1
   Install the Tor daemon

   On Linux: sudo apt install tor. The daemon must be running on ports 9150 (SOCKS) and 9151 (control).

2. 2
   Open the Tor panel

   Click the Tor icon in the left sidebar or navigate to the Tor section in Settings.

3. 3
   Click "Connect"

   The panel shows a bootstrap progress bar. When it reaches 100%, the browser restarts with all network traffic routed through Tor.

4. 4
   Get a new identity

   Click "New Identity" to request a fresh Tor circuit and a new exit IP address without restarting.

Profiles provide separate browser environments: cookies, local storage, cache, and privacy settings are completely isolated between profiles.

Switch profiles from the toolbar profile switcher (visible at window widths above 750 px). Each tab can optionally be pinned to a specific profile, allowing you to be logged into the same site with different accounts simultaneously.

Practical uses

• Personal vs. work browsing in the same window
• Testing web apps with different user accounts
• Separating social media sessions
• Research profiles with specific privacy settings

Katphi supports custom JavaScript injection into pages via its User Script Manager. Scripts are injected at page load time using Qt WebEngine's QWebEngineScript API.

Access the User Script Manager from the main menu. You can create, edit, enable, disable, and delete scripts. Each script targets a URL pattern and runs either at document start or document end.

Katphi's appearance is controlled by a centralised ThemeEngine (ui/core/theme_engine.py) that reads JSON theme files and applies design tokens across all UI components in real time.

Theme changes are broadcast via Qt signals, so every panel and widget updates instantly without a restart. Custom themes can be created as JSON files in the ui/themes/ directory.

The Search Engine Manager lets you define and switch the active search engine from a button in the toolbar. Katphi ships with several pre-configured engines and allows you to add custom ones.

You can also switch the engine temporarily for a single search by clicking the engine button and selecting an alternative — the default engine is not changed.

The Split View plugin (free, built-in) adds a persistent side panel to the right of the main content area. It behaves like an independent browser tab with its own navigation bar, URL input, back/forward/reload controls, and full context menu support.

How to activate

Right-click any tab in the tab bar and choose "Open in Split View". The Split View panel appears to the right of the current tabs. You can browse normally in the main area while the Split View keeps its own page visible.

Katphi's plugin system is designed for extensibility. Any developer can build a plugin and distribute it freely. Plugins are loaded dynamically at runtime from the plugins/ directory, with no browser restart required after installation.

How plugins work

1. 1
   Discovery

   The Plugin Manager scans plugins/ at startup and reads each plugin's plugin_info.json for its metadata.

2. 2
   Load

   The manager imports plugin.py via importlib and calls initialize_plugin().

3. 3
   Integration

   The plugin receives a reference to the browser window and can add panels, sidebar buttons, toolbar actions, and page hooks.

Built-in plugins

Building your own plugin

Katphi's plugin API is fully documented. Any Python developer can create a plugin that adds panels, toolbar buttons, page hooks, or entirely new features to the browser.

Refer to the Plugin Development Guide for the complete API reference, code templates, and step-by-step tutorials.

Press F12 to open the built-in DevTools panel, powered by Qt WebEngine's Chromium DevTools integration. It docks to the right or bottom of the window and provides the full Chromium DevTools experience: Elements, Console, Network, Sources, Performance, and more.

You can also open DevTools from the right-click context menu on any page by selecting "Inspect".

View Page Source

Press Ctrl+U to open the raw HTML source of the current page in a new tab.

The Log Viewer panel shows all internal browser log messages in real time with colour-coded severity levels.

Features: real-time auto-scroll, filter by level and module name, full-text search, and export to a plain-text file. Logs are also written to katphi_browser.log on disk with automatic rotation.

Navigation

Page

Panels & Tools

All persistent settings are stored in config.yaml at the project root. The file is loaded at startup by config_manager.py. You can edit it with any text editor; changes take effect on the next browser launch.

Sensitive values

Katphi does not read a .env file. AI provider keys (Anthropic, llmapi.ai, HuggingFace) are entered directly in the browser's AI settings panel and stored locally via Qt's QSettings — never in a plain-text file. The only value you should change by hand in config.yaml is security.secret_key, which ships with a placeholder and must be replaced before any production-like use.