⚡ OpenHotspot

A modern open-source Wi-Fi hotspot and network management toolkit for Linux.

OpenHotspot makes it easy to create, manage, diagnose, and share Wi-Fi hotspots on Linux without having to remember complex networking commands.

Built around NetworkManager (nmcli), OpenHotspot provides a clean CLI, system diagnostics, QR-code sharing, configuration management, and helpful troubleshooting.

🚀 Current Release: OpenHotspot 1.0 — "Apex"

✨ Why OpenHotspot?

Creating a hotspot on Linux is simple when everything works.

When it doesn't, troubleshooting can become frustrating due to Wi-Fi adapter limitations, driver capabilities, NetworkManager configuration, AP mode support, regulatory restrictions, and privilege management.

OpenHotspot wraps Linux networking tools in a user-friendly CLI while explaining why an operation succeeded or failed and how to resolve issues.

🌟 Core Features

• 📡 Hotspot Management: Easily start, stop, and restart Wi-Fi hotspots with custom SSID and WPA2-PSK security.
• 🔄 Concurrent Wi-Fi + Hotspot (AP+STA): Connect to an upstream Wi-Fi network while simultaneously broadcasting a hotspot on compatible hardware.
• 🩺 Doctor Diagnostics: Run an automated suite of system, driver, hardware, and permission checks.
• 📱 QR Code Sharing: Render terminal ASCII QR codes or export PNG images for instant mobile connection.
• 👥 Connected Client Detection: Monitor active connected stations via kernel neighbor tables and station dumps.
• ⚙️ Configuration Management: Persist global defaults in ~/.config/openhotspot/config.yaml.
• 📝 Local Logging: Retain rotating local logs for offline troubleshooting.
• 🔒 Local-First & Private: No cloud accounts, telemetry, or external API dependencies.
• 🛡️ Targeted Privilege Security: Runs in unprivileged user space; prompts for native OS authorization only when low-level wireless interface creation is required.

📊 Example Output

📡 OpenHotspot Status

Hotspot State       ● RUNNING
SSID                MyHotspot
AP Interface        oh-ap0
Physical Adapter    wlp2s0
Driver              ath10k_pci
Security Protocol   WPA2-PSK
Hotspot Gateway IP  10.42.0.1
Frequency Band      5 GHz
Wi-Fi Channel       149
Sharing Mode        Wi-Fi → Wi-Fi
Upstream            Campus_WiFi
Upstream State      CONNECTED
Internet Sharing    ACTIVE
Existing Wi-Fi      PRESERVED ✓

🛠️ System Dependencies

OpenHotspot relies on standard Linux networking utilities:

• NetworkManager (nmcli) — Manages network profiles, DHCP, and IP routing.
• iw — Required for virtual AP interface operations, AP+STA capability inspection, and frequency regulatory checks.
• iproute2 (ip) — Manages interface link states and IP addresses.

Installing Dependencies

On Ubuntu / Debian:

sudo apt update
sudo apt install network-manager iw iproute2

🚀 Installation

Preferred: Install via PyPI

pip install openhotspot

Virtual Environment Installation (Recommended for modern Linux distros)

python3 -m venv .venv
source .venv/bin/activate
pip install openhotspot

Install from Source

git clone https://github.com/joshisanidhya/openhotspot.git
cd openhotspot
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Verify installation:

openhotspot --version

⚡ Quick Start

1. Run Diagnostics

Check system compatibility and wireless capabilities:

openhotspot doctor

2. Start a Hotspot

openhotspot start --ssid "MyHotspot" --password "supersecret123"

Note on Administrative Authorization: OpenHotspot runs as a normal unprivileged application. If low-level wireless interface operations require elevated privileges, OpenHotspot requests authorization via native sudo. Password input is handled directly by your operating system terminal; OpenHotspot never sees, stores, or logs your password.

3. Check Hotspot Status

openhotspot status

4. Display Wi-Fi QR Code

openhotspot qr

5. Stop the Hotspot

openhotspot stop

💻 CLI Reference

See docs/cli-reference.md for detailed flag options.

📡 Wi-Fi + Hotspot Simultaneously (AP+STA)

OpenHotspot supports concurrent AP + STA mode, allowing your device to maintain an active Wi-Fi internet connection while broadcasting a hotspot.

• STA (Station): Your computer's client connection to an existing Wi-Fi router.
• AP (Access Point): The hotspot network broadcast by OpenHotspot.

Single-Channel Concurrency & Regulatory Considerations

Many Wi-Fi adapters support AP+STA operation on a single RF channel. In single-channel mode:

• OpenHotspot automatically matches the hotspot frequency band and channel to your upstream Wi-Fi connection.
• Driver or regulatory restrictions (such as DFS or No-Initiating-Radiation flags) MAY prevent initiating Access Point broadcasts on specific channels. OpenHotspot inspects frequency capabilities during preflight checks prior to activation.

Practical Alternatives

If concurrent AP+STA is unsupported by your hardware or restricted on your current channel:

• Connect upstream Wi-Fi to an AP-compatible non-DFS channel (e.g. 2.4 GHz or 5 GHz channels 36–48 / 149–165).
• Use Ethernet for internet upstream.
• Use a second USB Wi-Fi adapter.
• Run openhotspot start with --allow-disconnect to explicitly allow disconnecting existing Wi-Fi.

🩺 OpenHotspot Doctor Checks

openhotspot doctor performs the following diagnostic checks:

1. Linux Distribution & OS
2. Kernel Version
3. Python Runtime
4. NetworkManager Daemon & nmcli Availability
5. Wi-Fi Adapter & Wireless Driver Detection
6. Access Point (AP) Hardware Capability
7. Concurrent AP + STA Support & Channel Limits
8. Current Wi-Fi Upstream Channel & Regulatory Usability
9. Internet Connectivity
10. System Privilege & Authorization Status

See docs/doctor-diagnostics.md for diagnostic details.

🛡️ Security & Privilege Architecture

OpenHotspot prioritizes security and privilege minimization:

• Unprivileged Execution: OpenHotspot runs inside your normal user environment. Running the entire application as root (sudo openhotspot) is not required.
• Targeted Elevation: Elevated privileges are requested only for narrow kernel interface commands (e.g. iw).
• Native OS Credentials: Authentication is handled directly by sudo on your controlling terminal. OpenHotspot never captures, pipes, logs, or stores administrative credentials.

🏗️ Architecture

                    ┌─────────────────────────┐
                    │    Typer + Rich CLI     │
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │   Application Services  │
                    │ Hotspot │ Doctor │ QR   │
                    └───────┬──────────┬──────┘
                            │          │
                 ┌──────────▼───┐  ┌───▼──────────────┐
                 │NetworkManager│  │  Local Storage   │
                 │    nmcli     │  │  YAML / SQLite   │
                 └──────────────┘  └──────────────────┘

See docs/architecture.md for detailed component documentation.

🗺️ Roadmap

🚀 Apex — v1.x (Current Release)

• Core hotspot lifecycle management
• AP+STA concurrent sharing
• System Doctor diagnostics
• QR code generation
• Configuration and local logging

⚡ Titan — v2.x (Planned)

• Wi-Fi network scanning
• Advanced connected-device management
• Bandwidth monitoring & speed tests
• Historical usage analytics

👑 Dominion — v3.x (Planned)

• Desktop GUI interface
• Hotspot automation rules
• Local REST API
• Plugin architecture

See ROADMAP.md for details.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting pull requests.

Community interaction is governed by our CODE_OF_CONDUCT.md.

🔐 Security Policy

If you discover a potential security vulnerability, please refer to SECURITY.md to report it responsibly.

📜 License

Distributed under the MIT License.

⚡ OpenHotspot
Making Linux hotspot management simpler.