OpenWebTk

OpenWebTk is a browser-based control panel for launching and managing isolated instances of a Tkinter application. It starts each instance as a separate tkinter-web-backend process and proxies its HTTP and WebSocket traffic through the manager.

Repository: gitea.com/ProjectFS/OpenWebTk

Features

• Launch multiple instances of one Tkinter application.
• Open each running instance in its own browser tab.
• Stop an individual instance or stop all of your instances.
• View per-browser and server-wide instance limits.
• Keep instance processes and logs separate.
• Use a desktop-focused control panel with a mobile-device notice.

Requirements

• Python 3.10 or newer.
• A Tkinter application supported by tkinter-web-backend and its runtime requirements.
• Tk/Tcl installed and available to the Python environment where OpenWebTk runs. On some Linux distributions this is provided by a separate package, such as python3-tk.

Installation

Install OpenWebTk into the same Python environment that contains the dependencies for your Tkinter application. OpenWebTk uses that environment's Python interpreter to start each application instance.

After release, install from PyPI with:

python -m pip install openwebtk

To install from a source checkout, create and activate a virtual environment, then install the project in editable mode:

Windows PowerShell

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Linux / macOS

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Run

Pass the path to the Tkinter application as the required first argument:

openwebtk path/to/your_tkinter_app.py

For example, on Windows:

openwebtk "C:\path\to\your_tkinter_app.py"

You can also run the module directly with python -m openwebtk.

Open the address printed in the terminal. The default is http://localhost:8000. Use a desktop browser to manage instances. Each instance runs in a separate process; its output is written under the logs/ directory.

Configuration

openwebtk SCRIPT [options]

Options:
  -m, --max-instances N       Maximum simultaneous instances on the server (default: 30)
  --max-per-owner N           Maximum instances for one browser session (default: 5)
  --host HOST                 Manager bind address (default: 0.0.0.0)
  --port PORT                 Manager port (default: 8000)
  --ssl-certfile PATH         PEM certificate file; use with --ssl-keyfile
  --ssl-keyfile PATH          PEM private key file; use with --ssl-certfile
  --ssl-keyfile-password PASS Password for an encrypted private key

Example with custom limits and a local-only bind address:

openwebtk path/to/your_tkinter_app.py \
  --host 127.0.0.1 \
  --port 8000 \
  --max-instances 12 \
  --max-per-owner 3

The default host, 0.0.0.0, listens on all network interfaces. Choose 127.0.0.1 to make the manager reachable only from the same machine, or configure your network and firewall deliberately if remote access is needed.

HTTPS

Provide both a PEM certificate and its matching private key:

openwebtk path/to/your_tkinter_app.py \
  --ssl-certfile /path/to/fullchain.pem \
  --ssl-keyfile /path/to/private-key.pem

For an encrypted private key, provide --ssl-keyfile-password or set the SSL_KEYFILE_PASSWORD environment variable.

Session secret

OpenWebTk signs browser session cookies with SESSION_SECRET. If it is not set, a random secret is generated when the server starts, so existing browser sessions are invalidated after a restart. Set a long, unpredictable value to keep the signing key stable:

# Windows PowerShell
$env:SESSION_SECRET = "replace-with-a-long-random-value"

# Linux / macOS
export SESSION_SECRET="replace-with-a-long-random-value"

How instance access works

The manager keeps the instance registry in memory and assigns each browser session a private owner ID. Forms that start or stop instances use CSRF protection, and instance tokens are checked against that owner. When the manager shuts down, it terminates the child processes; running instances are not restored after a restart.

The mobile notice is based on browser device headers, with a narrow-screen CSS fallback. It is a device-use restriction for the interface, not a replacement for authentication.

Dependencies

The direct Python dependencies are listed in requirements.txt: FastAPI, Uvicorn, HTTPX, WebSockets, itsdangerous, python-multipart, and tkinter-web-backend. OpenWebTk uses Uvicorn with one worker because its process registry is held in memory.

Security notes

OpenWebTk does not provide user accounts or password-based authentication. The browser owner ID separates sessions, but anyone who can reach the manager can open their own session and use the configured instance capacity. Keep the service on a trusted network or put it behind an authenticated reverse proxy before exposing it beyond your machine. Use HTTPS when traffic crosses an untrusted network.