Metadata-Version: 2.4
Name: openwebtk
Version: 0.1.0
Summary: A browser-based control plane for running Tkinter application instances.
Project-URL: Repository, https://gitea.com/ProjectFS/OpenWebTk
Keywords: tkinter,web,gui,instance-manager,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: httpx>=0.27
Requires-Dist: websockets>=14.0
Requires-Dist: itsdangerous>=2.1
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: tkinter-web-backend

# 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](https://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:

```bash
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

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

### Linux / macOS

```bash
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:

```bash
openwebtk path/to/your_tkinter_app.py
```

For example, on Windows:

```powershell
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

```text
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:

```bash
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:

```bash
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:

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

```bash
# 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`](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.
