Skip to content

About

Windows desktop console for a Squad server: read-only SquadRS dashboard + local benchmark session. Built for SquadRS (https://squadrs.incoba.org/) by INCOBA.org (https://incoba.org/) — requires an API key from SquadRS.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Squad Server Console

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)

Why this exists

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.

Who builds it

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.

What it does

  • 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.

Quick start

  1. Download SquadServerConsole.zip from the Releases page.
  2. Unzip it into a folder you own (Desktop, Documents, a games folder), then open the SquadServerConsole\ folder. Do not use C:\Program Files — the app writes settings.json and server_maintenance.log beside the launcher.
  3. Double-click Start Squad Console.bat.
  4. Open Tools > Benchmark Parameters… (Ctrl+,) and paste your SquadRS API key into the Connection tab. The key is stored locally in settings.json; the SQUADRS_API_KEY environment 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.

Dashboard

  • 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.

Benchmark Parameters

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.

Build from source

On Windows with Python 3.12–3.14 and tkinter:

py -3 build_dist.py

Output:

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.

Releasing

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:

  1. Note the HEAD SHA of the release branch, then run the build workflow with workflow_dispatch on it and confirm the run's head_sha matches.
  2. 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.
  3. 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.

Tests

py -3 -m unittest test_core test_ui_model test_log_reader test_process_metrics test_gui

test_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.

Troubleshooting

  • 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-1 by 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.

About

Windows desktop console for a Squad server: read-only SquadRS dashboard + local benchmark session. Built for SquadRS (https://squadrs.incoba.org/) by INCOBA.org (https://incoba.org/) — requires an API key from SquadRS.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages