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 +24 -0
- m97-0.1.0/PKG-INFO +248 -0
- m97-0.1.0/README.md +222 -0
- m97-0.1.0/m97/__init__.py +3 -0
- m97-0.1.0/m97/__main__.py +7 -0
- m97-0.1.0/m97/access.py +160 -0
- m97-0.1.0/m97/app.py +351 -0
- m97-0.1.0/m97/cli.py +231 -0
- m97-0.1.0/m97/gufo.py +162 -0
- m97-0.1.0/m97/hub.py +364 -0
- m97-0.1.0/m97/intent.py +72 -0
- m97-0.1.0/m97/sensors.py +163 -0
- m97-0.1.0/m97/services.py +324 -0
- m97-0.1.0/m97/settings.py +85 -0
- m97-0.1.0/m97/settings.toml +51 -0
- m97-0.1.0/pyproject.toml +128 -0
- m97-0.1.0/tests/fixtures/after-metrics.txt +17 -0
- m97-0.1.0/tests/fixtures/busy-metrics.txt +51 -0
- m97-0.1.0/tests/fixtures/busy-slots.json +1 -0
- m97-0.1.0/tests/fixtures/gufo-log.txt +9 -0
- m97-0.1.0/tests/fixtures/idle-metrics.txt +51 -0
- m97-0.1.0/tests/fixtures/idle-slots.json +1 -0
- m97-0.1.0/tests/fixtures/props.json +1 -0
- m97-0.1.0/tests/fixtures/v1-models.json +1 -0
- m97-0.1.0/tests/test_access.py +109 -0
- m97-0.1.0/tests/test_cli.py +33 -0
- m97-0.1.0/tests/test_gufo.py +184 -0
- m97-0.1.0/tests/test_hub.py +123 -0
- m97-0.1.0/tests/test_intent.py +53 -0
- m97-0.1.0/tests/test_package.py +7 -0
- m97-0.1.0/tests/test_sensors.py +108 -0
- m97-0.1.0/tests/test_services.py +224 -0
- m97-0.1.0/tests/test_settings.py +78 -0
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
|
+

|
|
30
|
+
[](https://codecov.io/gh/Technologicat/m97)
|
|
31
|
+

|
|
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
|
+

|
|
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
|
+

|
|
4
|
+
[](https://codecov.io/gh/Technologicat/m97)
|
|
5
|
+

|
|
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
|
+

|
|
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).
|
m97-0.1.0/m97/access.py
ADDED
|
@@ -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.")
|