Windows desktop console for a Squad server: a read-only SquadRS status dashboard plus local session start/end and optional host teardown.
Version 0.5.1 · Windows 10/11 · Python 3.9+ (stdlib only)
Good community ideas often fail in practice on IT infrastructure and administration: tooling is missing, budgets are missing, and the default answer becomes dependence on commercial tech giants. This console is a different answer — a small, sovereign, transparent tool that a community can run and understand itself.
Built for SquadRS by INCOBA.org — the Infrastructure & Community Backbone Association, a non-profit digital incubator in Winterthur, Switzerland. Using the console requires an API key from SquadRS, entered per user under Tools → Benchmark Parameters. INCOBA provides technical infrastructure, organisational processes and knowledge so that engaged people can organise successfully: capacity building instead of bare IT. The Squad server this console maintains is part of that sovereign, community-run infrastructure — one pilot operation of the incubator.
- Shows server identity, map, heartbeat, occupancy, queue and endpoint availability without touching the game.
- Shows the live participant roster from SquadRS.
- Reads the local Squad client log for server/connection evidence: delayed ticks, missed ticks, worst tick interval, client RTC rate, the configured server tick cap, and DNS/ICMP/RTC warnings. Shader, cache and map-load noise is deliberately ignored.
- Samples the local Squad process on Windows: working-set memory, CPU time, and process I/O (disk and network aggregate). Labels say Process I/O, never network.
- Runs a local benchmark session: designated Start/End parameters.
- Optionally arms a host teardown countdown after the session ends.
- Keeps a local activity stream and a copyable diagnostics report.
The dashboard is read-only API/log data. No team, kill or event data is invented; anything the sources do not expose is shown as unknown. A failed API poll, absent process or unreadable log is a visible gap, never zero.
- Download
SquadServerConsole.zipfrom the Releases page. - Unzip it into a folder you own (Desktop, Documents, a games folder),
then open the
SquadServerConsole\folder. Do not useC:\Program Files— the app writessettings.jsonandserver_maintenance.logbeside the launcher. - Double-click
Start Squad Console.bat. - Open
Tools > Benchmark Parameters…(Ctrl+,) and paste your SquadRS API key into the Connection tab. The key is stored locally insettings.json; theSQUADRS_API_KEYenvironment variable is a fallback.
The first launch can take a few seconds. Windows SmartScreen may ask once
("More info" → "Run anyway") because the launcher is a plain .bat file.
- Command bar — server slug, state light, primary Start/End action.
- Left rail — server identity (ID, map, heartbeat) and session duration. Duplicate name/state/source blocks are intentionally omitted.
- Center — occupancy, queue, session timer and tick delays in the KPI strip; a dual-axis telemetry chart below it (left: Client RTC rate + dashed configured Server tick cap; right: Players, Queue + time-weighted rolling average; 30/60/90/120-minute window; avg 15/30/60 chips) with an API map timeline band under the axis; a local process row (CPU, Memory, Process I/O, Server heartbeat age); a log-only performance strip; and the participant roster. The center scrolls only when the window is too small for the content.
- Right rail — activity stream with level filter, API health and the last 60 endpoint samples.
- Status strip — current status, warnings, version.
Charts are timestamped in-memory series. The client RTC rate is derived only
from TicksCount / TimePeriod; the server tick cap comes from the log's
configured max tick rate and is a reference line, never a measured server
TPS. A failed poll or absent process is a visible gap, never a zero; no sample
is persisted or fabricated.
Tools > Benchmark Parameters… opens a single modal with five tabs:
- Connection — API key (masked), target server slug, sample interval, and
the Squad log file (blank auto-detects
%LOCALAPPDATA%\SquadGame\Saved\Logs\SquadGame.log). - Benchmark Parameters — start benchmark at/below N players, stop at/above N players, and optional HH:MM windows.
- Teardown — optional host power-off after the session ends, with delay.
- Automation — automatic client launch via handoff, status page fallback.
- Diagnostics — copy a report without the API key.
Changes apply immediately and the file is written after a short debounce. There is one Close button; there is no Save/Cancel pair.
On Windows with Python 3.12–3.14 and tkinter:
py -3 build_dist.pyOutput:
dist/SquadServerConsole/
dist/SquadServerConsole.zip
The builder downloads the pinned official embeddable Python runtime, grafts
tkinter from the local installation, copies the nine runtime modules and
writes Start Squad Console.bat.
Release v0.5.1 (the dispatched, smoke-tested commit) shipped this way on
2026-11-11: built by its CI workflow and smoke-tested on Windows, asset
SquadServerConsole.zip (21,897,598 B). v0.5.0 and v0.4.0 are earlier
releases from the same branch. The same order applies to the next release,
with the new version number:
- Note the HEAD SHA of the release branch, then run the build workflow with
workflow_dispatchon it and confirm the run'shead_shamatches. - Download the produced artifact and smoke-test it on Windows: the dashboard fits without scrolling, the process row shows live CPU/memory/Process I/O, and closed-Squad gaps appear as gaps.
- Only then tag the same SHA
vX.Y.Z; CI publishes the release asset. A failed tag run means delete the tag and release, fix, retag.
Day-to-day development happens in a separate private repository; this
repository publishes verified release snapshots. The old
squad-server-maintenance-tool repository is archived.
py -3 -m unittest test_core test_ui_model test_log_reader test_process_metrics test_guitest_core, test_ui_model, test_log_reader and test_process_metrics are
headless and also run on Linux.
test_gui contains structure checks plus a few display-only smoke tests that
skip when no usable Tk display is available.
HTTP 401— the API key is missing or invalid. Re-enter it in Connection.HTTP 404— the server slug does not exist. Check the value in Connection (fc-live-1by default).SquadRS API key not set— the app runs but polling is disabled until a key is added.- Server performance strip says log not found — set the Squad log path in
Tools > Benchmark Parameters… > Connection, or leave it blank on Windows. - No data / all charts empty — check the activity stream and
server_maintenance.log; the log keeps the full failure text. - App exits at launch — run from an open Command Prompt to keep the
traceback visible, and check
server_maintenance.crash.log.
The API key is sent only to the pinned SquadRS API host over HTTP (cleartext, accepted risk; see .docs/tech-debt.yaml). No telemetry is collected.