hysteria-panel-python/README.md

Hysteria Control Panel

A desktop GUI application for managing and monitoring a Hysteria2 server. It communicates with the server's HTTP API and presents live stats and controls in a modern Tk/ttkbootstrap UI.

Features

• Secure connection with API secret; optional HTTPS toggle.
• Connection profiles: remember host/port; optionally save the secret.
• Traffic monitoring: live TX/RX per user.
• Online users: view connections and kick selected users.
• Active streams viewer: JSON or plain-text view.
• Auto-refresh every 2 seconds (toggleable).

Requirements

• Python 3.13+ (matches pyproject.toml)
• A running Hysteria server with the API enabled.

Install & Run (uv)

From the hysteria-panel-python directory:

# Install dependencies and project in a venv
uv sync

# Launch the GUI via entry point
uv run hysteria-panel

# Alternatively run the module directly
uv run -m hysteria_panel

If you prefer pip:

python -m venv .venv
. .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .
hysteria-panel

Configuration

• Connection settings are stored in ~/.config/hysteria_panel/config.json (Linux/macOS). On Windows, the same path under your user profile is used.
• The “Use HTTPS” option switches the API scheme to https://{host}:{port}. Certificates are verified by default.
  • If your server uses a self-signed certificate and you need to disable verification, you can add an option—open an issue or PR.

Project Structure

• src/hysteria_panel/ package
  • __main__.py – application entry point
  • gui.py – main window and tab layout
  • api.py – HysteriaAPI client
  • utils.py – formatting and config helpers
  • views/ – tab views (Traffic, Online Users, Streams, Login)

Build

Build wheel/sdist artifacts to dist/:

uv build

Install the built wheel elsewhere:

uv pip install dist/*.whl

Troubleshooting

• No module named hysteria-panel: ensure the project is installed (uv sync or pip install -e .).
• Cannot connect: verify host/port/secret and whether HTTPS is required.