Skip to content

Quick Start Guide

Jump to bottom
Auto Bot Solutions edited this page Apr 27, 2026 · 1 revision

This guide provides step-by-step instructions for getting the Secure Browser system up and running quickly.

Table of Contents

Prerequisites

Before starting the Secure Browser system, ensure you have the following:

  • Python 3.7 or higher
  • pip (Python package manager)
  • Virtual environment (recommended)
  • Internet connection (for loading web pages)

Installation

Step 1: Navigate to the Project Directory

cd /home/robbie/Desktop/secure_browser

Step 2: Create a Virtual Environment (Recommended)

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

This will install:

  • PyQt5 and PyQtWebEngine (for PyQt5 browser)
  • tkinterweb (for Tkinter browser)
  • pywebview and qtpy (for WebView browser)

Step 4: Verify Installation

python3 main.py --help

Expected output:

usage: main.py [-h] [--browser {pyqt5,tkinter,webview,search}]

Secure Browser - A secure web browser implementation

options:
  -h, --help            show this help message and exit
  --browser {pyqt5,tkinter,webview,search}
                        Select browser implementation (default: pyqt5)

Starting the Browser

Option 1: Start with Default Browser (PyQt5)

python3 main.py

This launches the PyQt5 browser with the default homepage (https://search.brave.com/).

Option 2: Start with Specific Browser

# PyQt5 browser (default, feature-rich with tabs and dark theme)
python3 main.py --browser pyqt5

# Tkinter browser (lightweight, security-focused)
python3 main.py --browser tkinter

# WebView browser (native webview integration)
python3 main.py --browser webview

Option 3: Start Search Tool

python3 main.py --browser search

This launches the Advanced Search Operators Tool for building complex search queries.

Browser Options

PyQt5 Browser (hope.py)

Features:

  • Tabbed interface
  • Dark theme
  • Navigation controls (back, forward, reload, home)
  • Settings dialog (VPN, JavaScript, proxy)
  • Developer tools integration

Best for: Users who want a modern, feature-rich browser with tabbed browsing.

Usage:

python3 main.py --browser pyqt5

Tkinter Browser (secure_browser.py)

Features:

  • Lightweight
  • HTTPS enforcement
  • JavaScript toggle
  • Whitelist/blacklist filtering
  • Security headers
  • User-agent customization
  • Proxy support
  • Bookmarks

Best for: Users who prioritize security and privacy.

Usage:

python3 main.py --browser tkinter

WebView Browser (modern_browser.py)

Features:

  • Native webview integration
  • Navigation history
  • Proxy settings
  • Lightweight

Best for: Users who want native OS integration.

Usage:

python3 main.py --browser webview

Note: WebView browser may require system-level dependencies:

# Ubuntu/Debian:
sudo apt-get install python3-gi gir1.2-gtk-3.0

# Fedora:
sudo dnf install python3-gobject gtk3

Using the Search Tool

The Advanced Search Operators Tool helps you build complex search queries.

Launching the Search Tool

python3 main.py --browser search

Using the Tool

  1. Enter Base Query: Type your main search term in the query input field
  2. Add Operators: Use the checkboxes to add search operators:
    • Site: Restrict search to a specific website (e.g., docs.python.org)
    • Title: Search for terms in the page title (e.g., tutorial)
    • File Type: Search for specific file types (e.g., pdf, doc)
    • Exclude: Exclude terms from results (e.g., advertising)
    • Custom: Add custom search operators
  3. Preview Query: Click "Preview Query" to see the generated search string
  4. Execute Search: Click "Open in Browser" to execute the search in your default web browser

Example Search Queries

  • Search for Python tutorials on docs.python.org:

    Python tutorial site:docs.python.org

  • Search for PDF files about machine learning:

    machine learning filetype:pdf

  • Search for "tutorial" in page titles, excluding advertising:

    tutorial intitle:tutorial -advertising

Configuration

Default Configuration

The default homepage is set to https://search.brave.com/. You can customize this by editing config/user_settings.json:

{
  "home_url": "https://search.brave.com/",
  "security": {
    "https_enforcement": true,
    "javascript_enabled": true,
    "whitelist": [],
    "blacklist": []
  },
  "proxy": {
    "http": "",
    "https": ""
  }
}

Browser-Specific Settings

PyQt5 Browser:

  • Access settings via the "Settings" button in the navigation bar
  • Configure VPN usage, JavaScript, and proxy settings

Tkinter Browser:

  • Access settings via the "⚙ Settings" button
  • Configure user-agent, proxy, whitelist/blacklist, and JavaScript

WebView Browser:

  • Access settings via the "⚙ Settings" button
  • Configure user-agent and proxy settings

Troubleshooting

Issue: Module Not Found Error

Symptom:

ModuleNotFoundError: No module named 'PyQt5'

Solution:

# Activate virtual environment
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Issue: Browser Window Not Appearing

Symptom: Command executes but no window appears

Solution:

# Check display environment (Linux)
echo $DISPLAY

# If no display, set up virtual display
sudo apt-get install xvfb
xvfb-run python3 main.py

Issue: WebView Browser Not Working

Symptom: Error about GTK or Qt dependencies

Solution:

# Install GTK dependencies (Ubuntu/Debian)
sudo apt-get install python3-gi gir1.2-gtk-3.0

# Install Qt dependencies (if using Qt backend)
sudo apt-get install python3-pyqt5 python3-pyqt5.qtwebengine

Issue: CSS Warnings in PyQt5 Browser

Symptom: Warnings about "Unknown property box-shadow" or "transform"

Solution: These are non-critical warnings. Qt's stylesheet parser doesn't support all CSS3 properties. The browser still functions correctly.

Issue: Tkinter Browser Not Loading Pages

Symptom: Pages don't load or show errors

Solution:

# Verify tkinterweb installation
pip show tkinterweb

# Reinstall if needed
pip install --upgrade tkinterweb

Advanced Usage

Running in Background

To run the browser in the background:

python3 main.py &

Specifying Custom Homepage

Edit config/user_settings.json:

{
  "home_url": "https://your-custom-url.com"
}

Using Proxy

Configure proxy in browser settings or via environment variables:

export http_proxy="http://proxy.example.com:8080"
export https_proxy="https://proxy.example.com:8080"
python3 main.py

System Requirements

Minimum Requirements

  • Python 3.7+
  • 512 MB RAM
  • 100 MB disk space

Recommended Requirements

  • Python 3.9+
  • 1 GB RAM
  • 200 MB disk space
  • Internet connection

Next Steps

Support

For issues or questions:

Note: This project is actively maintained. For the latest updates, check the project repository.

Clone this wiki locally