m97 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
m97-0.1.0/LICENSE.md ADDED
@@ -0,0 +1,24 @@
1
+ BSD 2-Clause License
2
+
3
+ Copyright (c) 2026, Juha Jeronen
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ 2. Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
19
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
23
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
m97-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,248 @@
1
+ Metadata-Version: 2.4
2
+ Name: m97
3
+ Version: 0.1.0
4
+ Summary: A web dashboard and control panel for a gufo LLM server on AMD Strix Halo.
5
+ Keywords: gufo,llm,strix-halo,dashboard,podman,nicegui
6
+ Author-Email: Juha Jeronen <juha.jeronen@jamk.fi>
7
+ License-Expression: BSD-2-Clause
8
+ License-File: LICENSE.md
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Environment :: Web Environment
11
+ Classifier: Intended Audience :: End Users/Desktop
12
+ Classifier: Operating System :: POSIX :: Linux
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Programming Language :: Python :: 3.15
19
+ Classifier: Programming Language :: Python :: Implementation :: CPython
20
+ Classifier: Topic :: System :: Monitoring
21
+ Project-URL: Homepage, https://github.com/Technologicat/m97
22
+ Project-URL: Repository, https://github.com/Technologicat/m97
23
+ Requires-Python: >=3.11
24
+ Requires-Dist: nicegui>=4.0
25
+ Description-Content-Type: text/markdown
26
+
27
+ # m97
28
+
29
+ ![CI status](https://img.shields.io/github/actions/workflow/status/Technologicat/m97/ci.yml?branch=main)
30
+ [![codecov](https://codecov.io/gh/Technologicat/m97/branch/main/graph/badge.svg)](https://codecov.io/gh/Technologicat/m97)
31
+ ![license](https://img.shields.io/github/license/Technologicat/m97)
32
+
33
+ A web dashboard and control panel for a [gufo](https://github.com/gufo-org/gufo) LLM server on AMD Strix
34
+ Halo: what the machine and the model are doing — power, temperatures, memory, GPU and CPU load, generation
35
+ speed, recent requests — and buttons to start and stop gufo and [Open WebUI](https://github.com/open-webui/open-webui),
36
+ for the people in the household who never open a shell.
37
+
38
+ ![The m97 dashboard while gufo serves two chat requests](https://raw.githubusercontent.com/Technologicat/m97/main/docs/media/dashboard.png)
39
+
40
+ For my stance on AI contributions, see the [collaboration guidelines](https://github.com/Technologicat/substrate-independent/blob/main/collaboration.md).
41
+
42
+ ## Contents
43
+
44
+ - [Requirements](#requirements)
45
+ - [Install and uninstall](#install-and-uninstall)
46
+ - [Running it](#running-it)
47
+ - [Opening the dashboard](#opening-the-dashboard)
48
+ - [Configuration](#configuration)
49
+ - [Who can press the buttons](#who-can-press-the-buttons)
50
+ - [What it reads](#what-it-reads)
51
+ - [Development](#development)
52
+ - [License](#license)
53
+
54
+ ## Requirements
55
+
56
+ - Linux, on an AMD APU with the `amdgpu` driver. The sensors are read from sysfs; m97 was built on a Strix
57
+ Halo machine (Radeon 8060S, `gfx1151`).
58
+ - Rootless [podman](https://podman.io/), with gufo's host preparation done as in gufo's
59
+ [install guide](https://github.com/gufo-org/gufo/blob/main/docs/install.md): GPU device access, the GTT
60
+ size, unlimited locked memory. m97 runs gufo from its `gufo-runtime` container image.
61
+ - The model files, in a directory on the host (`~/models` by default).
62
+ - Python 3.11 or newer, and [pipx](https://pipx.pypa.io/) to install m97 in a virtualenv of its own.
63
+ - NetworkManager, to recognize trusted networks. Without it, m97 still runs, and treats every network as
64
+ untrusted.
65
+
66
+ ## Install and uninstall
67
+
68
+ ```bash
69
+ pipx install git+https://github.com/Technologicat/m97
70
+ ```
71
+
72
+ That puts the `m97` command on your `PATH`. To update, `pipx upgrade m97`, then `m97 install` again if you
73
+ run it as a service (see below), so the service picks up the new version.
74
+
75
+ To uninstall, remove the service first if you installed one, then the software:
76
+
77
+ ```bash
78
+ m97 uninstall
79
+ pipx uninstall m97
80
+ ```
81
+
82
+ Your settings file, `~/.config/m97/settings.toml`, is left in place; delete it by hand if you no longer
83
+ want it.
84
+
85
+ ## Running it
86
+
87
+ **As a service**, which is the usual way on a headless server. m97 then starts at boot and restarts if it
88
+ crashes:
89
+
90
+ ```bash
91
+ m97 install # install and enable the systemd user service, and start it
92
+ m97 status # running or not, and the URL to open
93
+ m97 stop # stop it
94
+ m97 start # start it again
95
+ m97 logs [-f] # its log (-f keeps following it)
96
+ m97 uninstall # stop, disable and remove the service
97
+ ```
98
+
99
+ The service serves the whole network. `m97 install --local` serves this machine only instead.
100
+
101
+ A systemd user service runs only while you are logged in, unless lingering is enabled for your user. For a
102
+ server that should start m97 at boot, before anyone logs in, enable it once:
103
+
104
+ ```bash
105
+ loginctl enable-linger "$USER"
106
+ ```
107
+
108
+ **Autostart.** m97 remembers which services were running, and when it starts, say at boot, it starts
109
+ them again. It waits for the network first, since a service started before the machine has joined a
110
+ trusted network would listen on this machine only. gufo comes first, and Open WebUI once gufo is up.
111
+
112
+ - A service counts as wanted running once m97 sees it running, however it was started: from the page, or
113
+ from a shell. It counts as wanted stopped once it has been down for half a minute while m97 runs.
114
+ - A service that stops by itself is reported on the page, with its exit code, its last log lines and what
115
+ to do. m97 does not restart it, and does not start it at boot until it has run again. The report stays
116
+ across a restart of m97.
117
+ - The state is kept in `~/.local/state/m97/state.json`. To turn autostart off, set `autostart = false` under
118
+ `[server]`.
119
+
120
+ **In the foreground**, for trying it out or for debugging. Ctrl+C stops it:
121
+
122
+ ```bash
123
+ m97 serve # this machine only
124
+ m97 serve --lan # the whole network
125
+ ```
126
+
127
+ ## Opening the dashboard
128
+
129
+ Point a web browser at port **8097** of the machine m97 runs on:
130
+
131
+ ```text
132
+ http://<server-name>:8097
133
+ ```
134
+
135
+ - `<server-name>` is the machine's hostname, if your router resolves hostnames; otherwise its mDNS name,
136
+ `<hostname>.local`, or its IP address.
137
+ - On the server itself, `http://127.0.0.1:8097` always works.
138
+ - `m97 status` prints the address, and says whether m97 listens on all interfaces or on this machine only;
139
+ `m97 serve` prints it at startup.
140
+
141
+ The port is a setting (`port` under `[server]`, below). The page needs no login: viewing is open to anyone
142
+ who can reach it, and only the buttons are guarded (see [who can press the buttons](#who-can-press-the-buttons)).
143
+
144
+ ## Configuration
145
+
146
+ m97 reads its settings from **`~/.config/m97/settings.toml`**. The file is optional: without it, m97 runs
147
+ on its defaults, which are in [`m97/settings.toml`](https://github.com/Technologicat/m97/blob/main/m97/settings.toml), each with a comment saying what it
148
+ does.
149
+
150
+ Your file overrides the defaults key by key, so it only needs the keys you want to change. A table in your
151
+ file merges into the default table of the same name; any other value, a list included, replaces the default
152
+ whole. A key m97 does not know is reported in its log as a probable typo and ignored. A value of the wrong
153
+ type stops m97 at startup with a message naming the key.
154
+
155
+ A typical file:
156
+
157
+ ```toml
158
+ [access]
159
+ pin = "2468" # a string, so that leading zeros survive
160
+
161
+ [[access.trusted_networks]]
162
+ name = "home"
163
+ connections = ["…UUID of the home Wi-Fi profile…"]
164
+ subnet = "192.168.1.0/24" # optional
165
+
166
+ [[access.trusted_networks]]
167
+ name = "cabin"
168
+ connections = ["…2.4 GHz profile…", "…5 GHz profile…"]
169
+
170
+ [gufo]
171
+ image = "ghcr.io/gufo-org/toolboxes/gufo-runtime:0.34.0" # pin a gufo version
172
+ sessions = 3
173
+ context = 262144
174
+ ```
175
+
176
+ The settings, by table:
177
+
178
+ - **`[server]`**: `port` (8097), and `autostart` (on; see [running it](#running-it)).
179
+ - **`[access]`**: the `pin`, and the `trusted_networks`; see [who can press the buttons](#who-can-press-the-buttons).
180
+ - **`[gufo]`**: how m97 runs gufo. `image`; `models_dir` (mounted read-only at `/models` in the container);
181
+ `model` and `mtp_model`, as paths relative to `models_dir` (an empty `mtp_model` turns speculative
182
+ decoding off); `served_name`, the model ID clients ask for; `sessions` and `context` (0 means gufo's own
183
+ default); `port`; `extra_args`, a list appended to the `gufo serve ... llm` command line; `container`, the
184
+ container's name; `start_timeout` in seconds. The defaults serve Qwen3.8 Flash-Next as in gufo's
185
+ quickstart.
186
+ - **`[openwebui]`**: `image`, `volume` (the podman volume that holds accounts and chats), `port`,
187
+ `container`, `start_timeout`. Open WebUI is pointed at gufo's port.
188
+ - **`[history]`**: `seconds` the graphs reach back (600), and the sampling `interval` (1.0).
189
+
190
+ m97 recognizes a service by its container name, so a container started some other way, by hand or by a
191
+ script, shows up on the page as long as the name matches.
192
+
193
+ ## Who can press the buttons
194
+
195
+ Viewing is always open. The start and stop buttons are open **while the server is on a trusted network**,
196
+ and need the **PIN** on any other network. With no PIN set, off the trusted networks they stay locked, and
197
+ the page says what to configure.
198
+
199
+ A trusted network is recognized by the UUID of the NetworkManager connection the server is using. List the
200
+ saved connections and their UUIDs with:
201
+
202
+ ```bash
203
+ nmcli -t -f NAME,UUID connection show
204
+ ```
205
+
206
+ A network with several saved profiles, say one per Wi-Fi band, lists all of them under `connections`. The
207
+ optional `subnet` adds a second condition: the server's address must also be inside it. A network that
208
+ has never been joined has no saved profile, and so no UUID yet; join it once, then add it.
209
+
210
+ NetworkManager offers a saved Wi-Fi profile only to an access point with the same name *and* compatible
211
+ security, so an open network that borrows a trusted network's name does not count as trusted. Anyone who
212
+ knows the Wi-Fi password could still set up a look-alike.
213
+
214
+ Two more things follow from the network:
215
+
216
+ - **Services started from the page listen on all interfaces only on a trusted network.** Elsewhere they
217
+ listen on this machine only, whoever pressed the button.
218
+ - **The PIN travels unencrypted**, since m97 serves plain HTTP. On an untrusted network, someone watching the
219
+ traffic could read it. Wrong guesses are limited to five per five minutes for each client address.
220
+
221
+ ## What it reads
222
+
223
+ Everything without root:
224
+
225
+ - **Host sensors** from sysfs and procfs: socket power, CPU (Tctl) and GPU edge temperatures, GPU load and
226
+ clock, CPU load, RAM, and GTT, the system memory the GPU has mapped. The sensors are found by driver
227
+ name, since hwmon indices change between boots.
228
+ - **gufo's HTTP endpoints**, only while its container runs: `/ready`, `/props`, `/slots` (which sessions are
229
+ busy, and their live speed), `/metrics` (the total generation throughput).
230
+ - **gufo's log**, for the recent requests: each finished chat request's token counts, speeds and timings.
231
+ - **Container state** from `podman events`, and **the network** from `nmcli monitor`, so m97 starts no
232
+ processes periodically. It takes about 0.5 % of one CPU core, plus about 0.1 % per open page (measured
233
+ on the server above).
234
+
235
+ ## Development
236
+
237
+ ```bash
238
+ git clone https://github.com/Technologicat/m97
239
+ cd m97
240
+ pdm install # creates .venv, installs m97 editable with the dev tools
241
+ pdm run pytest tests/
242
+ ```
243
+
244
+ The design, and the decisions behind it, are in [`briefs/done/dashboard.md`](https://github.com/Technologicat/m97/blob/main/briefs/done/dashboard.md).
245
+
246
+ ## License
247
+
248
+ BSD 2-Clause, see [`LICENSE.md`](https://github.com/Technologicat/m97/blob/main/LICENSE.md).
m97-0.1.0/README.md ADDED
@@ -0,0 +1,222 @@
1
+ # m97
2
+
3
+ ![CI status](https://img.shields.io/github/actions/workflow/status/Technologicat/m97/ci.yml?branch=main)
4
+ [![codecov](https://codecov.io/gh/Technologicat/m97/branch/main/graph/badge.svg)](https://codecov.io/gh/Technologicat/m97)
5
+ ![license](https://img.shields.io/github/license/Technologicat/m97)
6
+
7
+ A web dashboard and control panel for a [gufo](https://github.com/gufo-org/gufo) LLM server on AMD Strix
8
+ Halo: what the machine and the model are doing — power, temperatures, memory, GPU and CPU load, generation
9
+ speed, recent requests — and buttons to start and stop gufo and [Open WebUI](https://github.com/open-webui/open-webui),
10
+ for the people in the household who never open a shell.
11
+
12
+ ![The m97 dashboard while gufo serves two chat requests](https://raw.githubusercontent.com/Technologicat/m97/main/docs/media/dashboard.png)
13
+
14
+ For my stance on AI contributions, see the [collaboration guidelines](https://github.com/Technologicat/substrate-independent/blob/main/collaboration.md).
15
+
16
+ ## Contents
17
+
18
+ - [Requirements](#requirements)
19
+ - [Install and uninstall](#install-and-uninstall)
20
+ - [Running it](#running-it)
21
+ - [Opening the dashboard](#opening-the-dashboard)
22
+ - [Configuration](#configuration)
23
+ - [Who can press the buttons](#who-can-press-the-buttons)
24
+ - [What it reads](#what-it-reads)
25
+ - [Development](#development)
26
+ - [License](#license)
27
+
28
+ ## Requirements
29
+
30
+ - Linux, on an AMD APU with the `amdgpu` driver. The sensors are read from sysfs; m97 was built on a Strix
31
+ Halo machine (Radeon 8060S, `gfx1151`).
32
+ - Rootless [podman](https://podman.io/), with gufo's host preparation done as in gufo's
33
+ [install guide](https://github.com/gufo-org/gufo/blob/main/docs/install.md): GPU device access, the GTT
34
+ size, unlimited locked memory. m97 runs gufo from its `gufo-runtime` container image.
35
+ - The model files, in a directory on the host (`~/models` by default).
36
+ - Python 3.11 or newer, and [pipx](https://pipx.pypa.io/) to install m97 in a virtualenv of its own.
37
+ - NetworkManager, to recognize trusted networks. Without it, m97 still runs, and treats every network as
38
+ untrusted.
39
+
40
+ ## Install and uninstall
41
+
42
+ ```bash
43
+ pipx install git+https://github.com/Technologicat/m97
44
+ ```
45
+
46
+ That puts the `m97` command on your `PATH`. To update, `pipx upgrade m97`, then `m97 install` again if you
47
+ run it as a service (see below), so the service picks up the new version.
48
+
49
+ To uninstall, remove the service first if you installed one, then the software:
50
+
51
+ ```bash
52
+ m97 uninstall
53
+ pipx uninstall m97
54
+ ```
55
+
56
+ Your settings file, `~/.config/m97/settings.toml`, is left in place; delete it by hand if you no longer
57
+ want it.
58
+
59
+ ## Running it
60
+
61
+ **As a service**, which is the usual way on a headless server. m97 then starts at boot and restarts if it
62
+ crashes:
63
+
64
+ ```bash
65
+ m97 install # install and enable the systemd user service, and start it
66
+ m97 status # running or not, and the URL to open
67
+ m97 stop # stop it
68
+ m97 start # start it again
69
+ m97 logs [-f] # its log (-f keeps following it)
70
+ m97 uninstall # stop, disable and remove the service
71
+ ```
72
+
73
+ The service serves the whole network. `m97 install --local` serves this machine only instead.
74
+
75
+ A systemd user service runs only while you are logged in, unless lingering is enabled for your user. For a
76
+ server that should start m97 at boot, before anyone logs in, enable it once:
77
+
78
+ ```bash
79
+ loginctl enable-linger "$USER"
80
+ ```
81
+
82
+ **Autostart.** m97 remembers which services were running, and when it starts, say at boot, it starts
83
+ them again. It waits for the network first, since a service started before the machine has joined a
84
+ trusted network would listen on this machine only. gufo comes first, and Open WebUI once gufo is up.
85
+
86
+ - A service counts as wanted running once m97 sees it running, however it was started: from the page, or
87
+ from a shell. It counts as wanted stopped once it has been down for half a minute while m97 runs.
88
+ - A service that stops by itself is reported on the page, with its exit code, its last log lines and what
89
+ to do. m97 does not restart it, and does not start it at boot until it has run again. The report stays
90
+ across a restart of m97.
91
+ - The state is kept in `~/.local/state/m97/state.json`. To turn autostart off, set `autostart = false` under
92
+ `[server]`.
93
+
94
+ **In the foreground**, for trying it out or for debugging. Ctrl+C stops it:
95
+
96
+ ```bash
97
+ m97 serve # this machine only
98
+ m97 serve --lan # the whole network
99
+ ```
100
+
101
+ ## Opening the dashboard
102
+
103
+ Point a web browser at port **8097** of the machine m97 runs on:
104
+
105
+ ```text
106
+ http://<server-name>:8097
107
+ ```
108
+
109
+ - `<server-name>` is the machine's hostname, if your router resolves hostnames; otherwise its mDNS name,
110
+ `<hostname>.local`, or its IP address.
111
+ - On the server itself, `http://127.0.0.1:8097` always works.
112
+ - `m97 status` prints the address, and says whether m97 listens on all interfaces or on this machine only;
113
+ `m97 serve` prints it at startup.
114
+
115
+ The port is a setting (`port` under `[server]`, below). The page needs no login: viewing is open to anyone
116
+ who can reach it, and only the buttons are guarded (see [who can press the buttons](#who-can-press-the-buttons)).
117
+
118
+ ## Configuration
119
+
120
+ m97 reads its settings from **`~/.config/m97/settings.toml`**. The file is optional: without it, m97 runs
121
+ on its defaults, which are in [`m97/settings.toml`](https://github.com/Technologicat/m97/blob/main/m97/settings.toml), each with a comment saying what it
122
+ does.
123
+
124
+ Your file overrides the defaults key by key, so it only needs the keys you want to change. A table in your
125
+ file merges into the default table of the same name; any other value, a list included, replaces the default
126
+ whole. A key m97 does not know is reported in its log as a probable typo and ignored. A value of the wrong
127
+ type stops m97 at startup with a message naming the key.
128
+
129
+ A typical file:
130
+
131
+ ```toml
132
+ [access]
133
+ pin = "2468" # a string, so that leading zeros survive
134
+
135
+ [[access.trusted_networks]]
136
+ name = "home"
137
+ connections = ["…UUID of the home Wi-Fi profile…"]
138
+ subnet = "192.168.1.0/24" # optional
139
+
140
+ [[access.trusted_networks]]
141
+ name = "cabin"
142
+ connections = ["…2.4 GHz profile…", "…5 GHz profile…"]
143
+
144
+ [gufo]
145
+ image = "ghcr.io/gufo-org/toolboxes/gufo-runtime:0.34.0" # pin a gufo version
146
+ sessions = 3
147
+ context = 262144
148
+ ```
149
+
150
+ The settings, by table:
151
+
152
+ - **`[server]`**: `port` (8097), and `autostart` (on; see [running it](#running-it)).
153
+ - **`[access]`**: the `pin`, and the `trusted_networks`; see [who can press the buttons](#who-can-press-the-buttons).
154
+ - **`[gufo]`**: how m97 runs gufo. `image`; `models_dir` (mounted read-only at `/models` in the container);
155
+ `model` and `mtp_model`, as paths relative to `models_dir` (an empty `mtp_model` turns speculative
156
+ decoding off); `served_name`, the model ID clients ask for; `sessions` and `context` (0 means gufo's own
157
+ default); `port`; `extra_args`, a list appended to the `gufo serve ... llm` command line; `container`, the
158
+ container's name; `start_timeout` in seconds. The defaults serve Qwen3.8 Flash-Next as in gufo's
159
+ quickstart.
160
+ - **`[openwebui]`**: `image`, `volume` (the podman volume that holds accounts and chats), `port`,
161
+ `container`, `start_timeout`. Open WebUI is pointed at gufo's port.
162
+ - **`[history]`**: `seconds` the graphs reach back (600), and the sampling `interval` (1.0).
163
+
164
+ m97 recognizes a service by its container name, so a container started some other way, by hand or by a
165
+ script, shows up on the page as long as the name matches.
166
+
167
+ ## Who can press the buttons
168
+
169
+ Viewing is always open. The start and stop buttons are open **while the server is on a trusted network**,
170
+ and need the **PIN** on any other network. With no PIN set, off the trusted networks they stay locked, and
171
+ the page says what to configure.
172
+
173
+ A trusted network is recognized by the UUID of the NetworkManager connection the server is using. List the
174
+ saved connections and their UUIDs with:
175
+
176
+ ```bash
177
+ nmcli -t -f NAME,UUID connection show
178
+ ```
179
+
180
+ A network with several saved profiles, say one per Wi-Fi band, lists all of them under `connections`. The
181
+ optional `subnet` adds a second condition: the server's address must also be inside it. A network that
182
+ has never been joined has no saved profile, and so no UUID yet; join it once, then add it.
183
+
184
+ NetworkManager offers a saved Wi-Fi profile only to an access point with the same name *and* compatible
185
+ security, so an open network that borrows a trusted network's name does not count as trusted. Anyone who
186
+ knows the Wi-Fi password could still set up a look-alike.
187
+
188
+ Two more things follow from the network:
189
+
190
+ - **Services started from the page listen on all interfaces only on a trusted network.** Elsewhere they
191
+ listen on this machine only, whoever pressed the button.
192
+ - **The PIN travels unencrypted**, since m97 serves plain HTTP. On an untrusted network, someone watching the
193
+ traffic could read it. Wrong guesses are limited to five per five minutes for each client address.
194
+
195
+ ## What it reads
196
+
197
+ Everything without root:
198
+
199
+ - **Host sensors** from sysfs and procfs: socket power, CPU (Tctl) and GPU edge temperatures, GPU load and
200
+ clock, CPU load, RAM, and GTT, the system memory the GPU has mapped. The sensors are found by driver
201
+ name, since hwmon indices change between boots.
202
+ - **gufo's HTTP endpoints**, only while its container runs: `/ready`, `/props`, `/slots` (which sessions are
203
+ busy, and their live speed), `/metrics` (the total generation throughput).
204
+ - **gufo's log**, for the recent requests: each finished chat request's token counts, speeds and timings.
205
+ - **Container state** from `podman events`, and **the network** from `nmcli monitor`, so m97 starts no
206
+ processes periodically. It takes about 0.5 % of one CPU core, plus about 0.1 % per open page (measured
207
+ on the server above).
208
+
209
+ ## Development
210
+
211
+ ```bash
212
+ git clone https://github.com/Technologicat/m97
213
+ cd m97
214
+ pdm install # creates .venv, installs m97 editable with the dev tools
215
+ pdm run pytest tests/
216
+ ```
217
+
218
+ The design, and the decisions behind it, are in [`briefs/done/dashboard.md`](https://github.com/Technologicat/m97/blob/main/briefs/done/dashboard.md).
219
+
220
+ ## License
221
+
222
+ BSD 2-Clause, see [`LICENSE.md`](https://github.com/Technologicat/m97/blob/main/LICENSE.md).
@@ -0,0 +1,3 @@
1
+ """A web dashboard and control panel for a gufo LLM server on AMD Strix Halo."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,7 @@
1
+ """`python -m m97`, which is what the systemd unit runs."""
2
+
3
+ import sys
4
+
5
+ from .cli import main
6
+
7
+ sys.exit(main())
@@ -0,0 +1,160 @@
1
+ """Who may press the buttons: anyone while the machine is on a trusted network, and elsewhere whoever knows the PIN.
2
+
3
+ Viewing is always open; only starting and stopping services is gated. A trusted network is recognized by the
4
+ UUID of the NetworkManager connection the machine is using, optionally narrowed by a subnet. NetworkManager
5
+ offers a saved Wi-Fi profile only to an access point with the same SSID *and* compatible security, so a WPA
6
+ profile is not matched by an open network that borrows its name.
7
+ """
8
+
9
+ import dataclasses
10
+ import hmac
11
+ import ipaddress
12
+ import logging
13
+ import subprocess
14
+ import time
15
+
16
+ __all__ = ["active_connections", "parse_active_connections", "parse_addresses",
17
+ "trusted_network",
18
+ "pin_matches", "make_rate_limiter",
19
+ "Decision", "decide"]
20
+
21
+ logger = logging.getLogger(__name__)
22
+
23
+
24
+ # --------------------------------------------------------------------------------
25
+ # What network the machine is on
26
+
27
+ def parse_active_connections(text):
28
+ """Parse `nmcli -t -f UUID,DEVICE connection show --active` into a list of `(uuid, device)`."""
29
+ connections = []
30
+ for line in text.splitlines():
31
+ uuid, sep, device = line.partition(":")
32
+ if sep and uuid:
33
+ connections.append((uuid, device))
34
+ return connections
35
+
36
+
37
+ def parse_addresses(text):
38
+ """Parse `nmcli -g IP4.ADDRESS device show <dev>` into a list of `ipaddress.IPv4Interface`.
39
+
40
+ nmcli separates several addresses with ` | `; anything that is not an address is skipped.
41
+ """
42
+ addresses = []
43
+ for item in text.replace("|", "\n").split():
44
+ try:
45
+ addresses.append(ipaddress.ip_interface(item))
46
+ except ValueError:
47
+ continue
48
+ return addresses
49
+
50
+
51
+ def _nmcli(*args):
52
+ result = subprocess.run(["nmcli", "-t", *args], capture_output=True, text=True, timeout=5)
53
+ result.check_returncode()
54
+ return result.stdout
55
+
56
+
57
+ def active_connections():
58
+ """Return the machine's active NetworkManager connections as a list of `(uuid, [addresses])`.
59
+
60
+ Empty if NetworkManager is not there or does not answer, which makes every network untrusted.
61
+ """
62
+ try:
63
+ connections = parse_active_connections(_nmcli("-f", "UUID,DEVICE", "connection", "show", "--active"))
64
+ return [(uuid, parse_addresses(_nmcli("-g", "IP4.ADDRESS", "device", "show", device)) if device else [])
65
+ for uuid, device in connections]
66
+ except (OSError, subprocess.SubprocessError) as exc:
67
+ logger.warning(f"could not ask NetworkManager for the active connections, so no network is trusted: {exc}")
68
+ return []
69
+
70
+
71
+ def trusted_network(networks, connections):
72
+ """Return the name of the trusted network the machine is on, or `None`.
73
+
74
+ `networks` is the `access.trusted_networks` setting: a list of tables with `name`, `connections` (a list
75
+ of connection UUIDs) and optionally `subnet`. `connections` is what `active_connections` returns. A
76
+ network matches when one of its UUIDs is active and, if it names a subnet, that connection has an
77
+ address inside it.
78
+ """
79
+ for network in networks:
80
+ uuids = set(network.get("connections", []))
81
+ maybe_subnet = network.get("subnet")
82
+ try:
83
+ subnet = ipaddress.ip_network(maybe_subnet, strict=False) if maybe_subnet else None
84
+ except ValueError:
85
+ logger.warning(f"trusted network {network.get('name')!r}: `subnet` {maybe_subnet!r} is not a subnet, "
86
+ f"so the network never matches")
87
+ continue
88
+ for uuid, addresses in connections:
89
+ if uuid not in uuids:
90
+ continue
91
+ if subnet is None or any(address.ip in subnet for address in addresses):
92
+ return network.get("name") or uuid
93
+ return None
94
+
95
+
96
+ # --------------------------------------------------------------------------------
97
+ # The PIN
98
+
99
+ def pin_matches(configured, given):
100
+ """Whether `given` is the configured PIN. An empty configured PIN matches nothing."""
101
+ if not configured:
102
+ return False
103
+ return hmac.compare_digest(configured.encode("utf-8"), (given or "").encode("utf-8"))
104
+
105
+
106
+ def make_rate_limiter(*, max_failures=5, window=300.0, clock=time.monotonic):
107
+ """Make a limiter for wrong PINs: at most `max_failures` per client within `window` seconds.
108
+
109
+ Returns `(allowed, record_failure)`. `allowed(client)` says whether the client may try now;
110
+ `record_failure(client)` counts a wrong PIN. `client` is any hashable key, e.g. the client's address.
111
+ """
112
+ # Against a four-digit PIN: 10^4 values, so 5,000 guesses on average; at the defaults, one guess a minute,
113
+ # that is 5,000 min ≈ 3.5 days per address, and a week to exhaust the space.
114
+ failures = {} # client -> monotonic times of recent failures
115
+
116
+ def recent(client):
117
+ now = clock()
118
+ times = [t for t in failures.get(client, []) if now - t < window]
119
+ if times:
120
+ failures[client] = times
121
+ else:
122
+ failures.pop(client, None)
123
+ return times
124
+
125
+ def allowed(client):
126
+ return len(recent(client)) < max_failures
127
+
128
+ def record_failure(client):
129
+ failures.setdefault(client, []).append(clock())
130
+
131
+ return allowed, record_failure
132
+
133
+
134
+ # --------------------------------------------------------------------------------
135
+ # The decision the page shows
136
+
137
+ @dataclasses.dataclass(frozen=True, kw_only=True)
138
+ class Decision:
139
+ """Whether the buttons are open, and a sentence for the page saying why.
140
+
141
+ `allowed`: open without a PIN. `pin_required`: a PIN would open them. Both false: locked, and `reason`
142
+ says what to configure.
143
+ """
144
+ allowed: bool
145
+ pin_required: bool
146
+ reason: str
147
+
148
+
149
+ def decide(access_settings, connections):
150
+ """Decide whether the buttons are open, given the `access` settings and the active connections."""
151
+ name = trusted_network(access_settings.get("trusted_networks", []), connections)
152
+ if name is not None:
153
+ return Decision(allowed=True, pin_required=False, reason=f"On the trusted network “{name}”.")
154
+ if access_settings.get("pin"):
155
+ return Decision(allowed=False, pin_required=True,
156
+ reason="Not on a trusted network: enter the PIN to use the buttons.")
157
+ return Decision(allowed=False, pin_required=False,
158
+ reason="Locked: this machine is not on a trusted network, and no PIN is set. To use the buttons "
159
+ "here, set `pin` under `[access]` in ~/.config/m97/settings.toml, or add this network "
160
+ "to `trusted_networks` there.")