@andrian.yablonskyy/thub-coordinator 1.0.37 → 1.0.39

package/views/help/_agent-cli.pug

@@ -0,0 +1,103 @@
++section('agent-cli', 'Agent CLI reference', 'code-square')
+  h3.h6 Commands
+  +code('thub --help').
+    thub run      [options]                 Submit a job and follow its log
+    thub status   <jobId> [--json]          Status; follow the log if running, verdict and test counts if done
+    thub cancel   <jobId>                   Cancel a job
+    thub resources [--json]                 Clients and their status
+    thub jobs     [--mine] [--state <s>] [--json]   Recent jobs
+    thub config   set <url|token|group|user> <value>
+    thub check-update                       Compare with the latest published Agent
+    thub self-update [--to <x.y.z>]         Update with npm i -g
+    thub --version
+    Global: --url <url>  --token <token>   (override THUB_URL / THUB_TOKEN / config file)
+
+  h3.h6 #[code thub run] options
+  -
+    const groups = [
+      { title: 'Where to run', rows: [
+        ['--type hw|sw', 'Required. Resource type.', '--type hw'],
+        ['--board <name>', 'Shorthand for --label board:<name>.', '--board nucleo-f401re'],
+        ['--label <l>', 'Required label (repeatable). The Client must have all of them.', '--label uart --label stlink'],
+        ['--group <id>', 'Only Clients in this group. Default: THUB_GROUP / config.', '--group 548ae4ae-…'],
+        ['--client <name|id>', 'Only this Client; waits for it even if others are idle.', '--client lab-hw-01']
+      ] },
+      { title: 'What to run', rows: [
+        ['--command <string>', 'Required. Run with sh -c in the work directory. Exit code 0 = PASSED.', "--command './ci/test.sh'"],
+        ['--arg <value>', 'Argument for the command, as "$@" (repeatable).', '--arg --junit --arg -v'],
+        ['--suite <name>', 'Passed as THUB_SUITE (default: default).', '--suite smoke'],
+        ['--download-file <url>', 'File downloaded before the command (repeatable, http(s), no credentials). THUB_DOWNLOAD_1…', '--download-file https://…/app.bin'],
+        ['--git-repo <url> [ref]', 'Repository cloned first; the command runs in it.', '--git-repo git@github.com:org/tests.git v1.4.0'],
+        ['--depth <n>', 'Commits to fetch with --git-repo (default 1, 0 = full).', '--depth 0'],
+        ['--git-options <string>', 'Extra git options between git and its subcommand. Stored with the job.', '--git-options \'-c core.sshCommand="ssh -i ~/.ssh/k"\''],
+        ['--docker-image <ref>', 'SW only: DUT container image, pulled with the Client host’s Docker login.', '--docker-image registry.lab:5000/emu:1'],
+        ['--env <vars>', 'NAME=value[,NAME=value] for git and the command (repeatable). --env NAME takes the value from your shell. Masked, dropped at job end.', '--env TARGET=staging --env API_TOKEN']
+      ] },
+      { title: 'Job settings', rows: [
+        ['--timeout <dur>', 'e.g. 30m, 1h (default 30m, capped by the Coordinator).', '--timeout 1h'],
+        ['--priority <n>', '0–100. Defaults: ci 50, cli 60.', '--priority 80'],
+        ['--user <name>', 'Free-text owner label. Default: THUB_USER / config.', '--user alice'],
+        ['--meta <key=value>', 'Metadata stored on the job (repeatable). The command sees THUB_META_<KEY>.', '--meta ciJobId=$GITHUB_RUN_ID'],
+        ['--dry-run', 'Schedule for real, but only log what the Client would run.', '--dry-run']
+      ] },
+      { title: 'Agent behavior', rows: [
+        ['--wait', 'Follow to the end and exit with the verdict code (CI). Ctrl-C/SIGINT cancels the job.', '--wait'],
+        ['--detach', 'Print the job id and exit.', '--detach --json'],
+        ['--json', 'Machine-readable output.', '--json']
+      ] }
+    ]
+  each g in groups
+    h4.h6.text-body-secondary.mt-3= g.title
+    .table-responsive
+      table.table.table-sm.small.align-middle
+        thead
+          tr
+            th(style="width: 22%") Option
+            th Description
+            th(style="width: 32%") Example
+        tbody
+          each r in g.rows
+            tr
+              td: code.text-nowrap= r[0]
+              td= r[1]
+              td: code= r[2]
+
+  h3.h6 Exit codes
+  table.table.table-sm.small.w-auto
+    tbody
+      each e in [['0', 'PASSED'], ['1', 'FAILED'], ['2', 'ERROR, TIMEOUT or LOST'], ['3', 'CANCELED'], ['4', 'Usage, auth or connection error'], ['5', 'thub status --json: still queued or running'], ['130', 'Detached with Ctrl-C (job keeps running)']]
+        tr
+          td: code= e[0]
+          td= e[1]
+
+  h3.h6 Examples
+  +code('Flash and test a board, fail CI on failure').
+    thub run --type hw --board nucleo-f401re \
+      --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
+      --git-repo https://github.com/yourorg/firmware-tests.git v1.4.0 \
+      --command 'st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh "$@"' \
+      --arg --junit --timeout 45m --wait
+  +code('Reproduce a failure on the exact bench, labeled with your name').
+    thub run --type hw --board nucleo-f401re --client lab-hw-01 --user "$USER" \
+      --download-file "$IMAGE_URL" --git-repo "$TESTS_REPO" --command ./ci/test.sh
+    # Ctrl-C detaches; the job keeps running. Re-attach:
+    thub status M-00126
+  +code('Verify a download before using it').
+    thub run --type hw --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
+      --command 'echo "8f15bf27…  $THUB_DOWNLOAD_1" | sha256sum -c && ./flash.sh "$THUB_DOWNLOAD_1"' --wait
+  +code('Secrets and parameters').
+    export API_TOKEN=…
+    thub run --type sw --git-repo "$TESTS_REPO" \
+      --env TARGET=staging,LOG_LEVEL=debug --env API_TOKEN \
+      --command './run-tests.sh --target "$TARGET"' --suite regression --wait
+  +code('Preview exactly what would run (nothing is executed)').
+    thub run --type sw --docker-image alpine --git-repo https://example.invalid/tests.git main \
+      --command ./ci/test.sh --dry-run --wait
+  +code('Scripting: submit, poll, read the result').
+    JOB=$(thub run --type sw --git-repo "$TESTS_REPO" --command ./ci/test.sh --detach --json | jq -r .jobId)
+    while thub status "$JOB" --json > job.json; [ $? -eq 5 ]; do sleep 10; done
+    jq -r '"\(.state) exit=\(.exit_code) tests=\(.summary.total // 0) failed=\(.summary.failed // 0)"' job.json
+  +code('Lists').
+    thub resources
+    thub jobs --mine --state FAILED
+    thub cancel M-00126

package/views/help/_agent-setup.pug

@@ -0,0 +1,72 @@
++section('agent-setup', 'Agent setup', 'terminal')
+  p.
+    The Agent (#[code thub]) is a stateless Node.js CLI. Install it wherever jobs are submitted from:
+    a developer machine (macOS, Linux or Windows with Node.js 20+) or a CI runner.
+
+  h3.h6 Install
+  +code('Developer machine').
+    npm i -g @andrian.yablonskyy/thub-agent
+    thub --version
+  p.small.
+    In CI you don't need a global install: #[code npx -y @andrian.yablonskyy/thub-agent run …].
+
+  h3.h6 Get a token
+  p.small.
+    An admin registers an agent on #[a(href="/admin/agents") Agents] (or with #[code thub-admin agent add]) and passes you
+    its token, which is shown only once. The agent's #[strong kind] decides the job id prefix and the default priority:
+  table.table.table-sm.small.w-auto
+    thead
+      tr
+        th Kind
+        th For
+        th Job ids
+        th Default priority
+    tbody
+      tr
+        td: code ci
+        td Pipelines
+        td: code A-00001…
+        td 50
+      tr
+        td: code cli
+        td Developers
+        td: code M-00001…
+        td 60 (so a busy pipeline doesn't starve them)
+
+  h3.h6 Configure
+  +code('Save the settings once').
+    thub config set url   #{coordinatorUrl}
+    thub config set token agt_…
+    thub config set user  "Your Name"      # optional: job owner label
+    thub config set group <groupId>       # optional: default --group
+  p.small.
+    These are saved in #[code ~/.config/thub/agent.json]. Order of precedence: flags (#[code --url], #[code --token]) →
+    environment → config file.
+  table.table.table-sm.small
+    thead
+      tr
+        th Variable
+        th Meaning
+    tbody
+      tr
+        td: code THUB_URL
+        td Coordinator URL, e.g. #[code #{coordinatorUrl}]
+      tr
+        td: code THUB_TOKEN
+        td Agent token. Keep it in your CI's secret store.
+      tr
+        td: code THUB_GROUP
+        td Default #[code --group]
+      tr
+        td: code THUB_USER
+        td Default #[code --user]
+      tr
+        td: code THUB_NO_SELF_UPDATE=1
+        td Don't install admin-requested Agent updates on this machine
+  +code('Check the connection').
+    thub resources          # lists the Clients and their status
+    thub jobs --mine        # your recent jobs
+  p.small.mb-0.
+    When an admin requests an Agent update, the next #[code thub] command installs it and then runs on
+    the new version. If it can't install (e.g. no permission in CI), it prints the manual command and
+    carries on with the current version.

package/views/help/_ci.pug

@@ -0,0 +1,44 @@
++section('ci', 'CI/CD integration (GitHub Actions)', 'github')
+  p.
+    The test job only needs the Agent and HTTPS access to the Coordinator, so it runs on an ordinary hosted runner.
+    Create a #[strong ci]-kind agent on #[a(href="/admin/agents") Agents] and store its token as the repository secret
+    #[code THUB_AGENT_TOKEN].
+  +code('.github/workflows/firmware.yml').
+    name: firmware
+    on: [push, pull_request]
+
+    jobs:
+      build:
+        runs-on: [self-hosted, fw-build]
+        outputs:
+          image_url: ${{ steps.upload.outputs.image_url }}
+        steps:
+          - uses: actions/checkout@v4
+          - run: cmake -B build -G Ninja && cmake --build build
+          - id: upload
+            env: { ART_TOKEN: "${{ secrets.ARTIFACTORY_TOKEN }}" }
+            run: |
+              URL="https://artifactory.example.com/fw-local/app/${GITHUB_SHA::7}-${GITHUB_RUN_NUMBER}/app.bin"
+              curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T build/app.bin "$URL"
+              echo "image_url=$URL" >> "$GITHUB_OUTPUT"
+
+      test-hw:
+        needs: build
+        runs-on: ubuntu-latest
+        env:
+          THUB_URL: #{coordinatorUrl}
+          THUB_TOKEN: ${{ secrets.THUB_AGENT_TOKEN }}
+        steps:
+          - run: |
+              npx -y @andrian.yablonskyy/thub-agent run \
+                --type hw --board nucleo-f401re \
+                --download-file "${{ needs.build.outputs.image_url }}" \
+                --git-repo "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.git" "$GITHUB_SHA" \
+                --command 'st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/hw-tests.sh' \
+                --suite smoke --timeout 30m --wait \
+                --meta runUrl="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+  ul.small.mb-0
+    li The step's exit code is the verdict (#[a(href="#agent-cli") exit codes]), so the workflow fails exactly when the tests do.
+    li If the workflow is canceled, the Agent (in #[code --wait] mode) cancels the TestHub job, so abandoned runs don't hold hardware.
+    li Downloads carry no credentials. Publish the image to a URL the Client can read, or fetch it in #[code --command] with a token passed as #[code --env].
+    li Other CI systems (GitLab CI, Jenkins, Azure Pipelines) work the same way: install Node.js, set #[code THUB_URL]/#[code THUB_TOKEN] and run #[code thub run … --wait].

package/views/help/_client-machines.pug

@@ -0,0 +1,87 @@
++section('client-machines', 'Client machines: HW and SW', 'pc')
+  p.
+    Which machine you need depends on what the jobs run against. Clients are supported on
+    #[strong Ubuntu 26.04]; other systemd-based Linux distributions work the same way in practice.
+    Every Client machine needs outbound HTTPS to the Coordinator (and to wherever jobs download from:
+    Artifactory, git servers, Docker registries). Nothing inbound.
+
+  .row.g-3.mb-3
+    .col-md-6
+      .card.h-100.border-primary-subtle
+        .card-header
+          i.bi.bi-cpu.me-1
+          strong HW Client: real machine with a physical DUT
+        .card-body.small
+          ul.mb-0
+            li A physical machine (a mini-PC, NUC or Raspberry-class ARM64 board) next to the bench.
+            li USB for the DUT's debugger (ST-Link), USB-serial adapters (UART) and DUT USB. A #[strong powered USB hub] is recommended.
+            li #[code stlink-tools] and/or #[code openocd], #[code usbutils] (for the dashboard's USB scan).
+            li Docker only if jobs run containers in their #[code --command].
+            li One Client instance per board. One machine can drive several boards (up to 8 ST-Links, UARTs and USB devices per instance).
+    .col-md-6
+      .card.h-100.border-success-subtle
+        .card-header
+          i.bi.bi-pc-display.me-1
+          strong SW Client: real or virtual machine, software-only jobs
+        .card-body.small
+          ul.mb-0
+            li Any Linux host: bare metal, a VM (Proxmox, VMware, Hyper-V, KVM) or a cloud instance.
+            li Docker Engine (#[code docker.io]), with the Client's service user in the #[code docker] group (the installer arranges this).
+            li Each job's DUT container is limited to 2 CPUs and 2 GB RAM. Size the VM for one job plus your test tools: 4 vCPU, 8 GB RAM and 40 GB+ disk for images and workspaces is a good start.
+            li For KVM-accelerated emulators (QEMU) inside a VM, turn on #[strong nested virtualization].
+            li No USB or udev setup.
+
+  h3.h6 Preparing an HW machine
+  ol.small
+    li Install the OS and the Client (#[a(href="#client-setup") Client setup]), then plug in the board's ST-Link, UART adapter and DUT USB.
+    li
+      | Find each device's USB #[strong port path] (#[code devpath]). It's stable across replugs as long as the device stays in the same port:
+      +code('HW machine').
+        lsusb -t                                      # USB tree
+        udevadm info -a -n /dev/ttyUSB0 | grep -m1 'ATTRS{devpath}'
+        st-info --probe                               # ST-Link serials
+      | Or open the resource card → #[strong Connected USB devices] → #[strong Refresh], then #[strong Import to config].
+    li
+      | Put the devpaths into #[code hw-devices] and restart. On every start the Client writes
+      | #[code /etc/udev/rules.d/99-thub-<instance>.rules], so the devices appear as #[code /dev/thub/dut<N>-stlink|uart|usb]:
+      +code('HW machine').
+        sudo systemctl restart thub-client@client
+        ls -l /dev/thub/
+    li Check the resource card's #[strong Capabilities]: each configured device must be present (a missing one is flagged).
+    li Your job's #[code --command] flashes the board. The Client never flashes by itself; it passes the ST-Link serials and the downloaded files in the environment (#[a(href="#env") Environment variables]).
+  +code('A typical HW job').
+    thub run --type hw --board nucleo-f401re \
+      --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
+      --git-repo https://github.com/yourorg/firmware-tests.git v1.4.0 \
+      --command 'st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh' \
+      --wait
+
+  +note('warning').
+    #[strong HW in a VM?] USB passthrough works, but the #[code devpath] then reflects the #[em virtual] USB topology and
+    can change when the hypervisor reassigns devices. Serial timing-sensitive tests may also suffer. Use a physical machine for HW Clients.
+
+  h3.h6 Preparing an SW machine (real or virtual)
+  +code('SW machine / VM').
+    sudo apt install -y nodejs npm docker.io
+    sudo npm i -g @andrian.yablonskyy/thub-client
+    nano ~/.config/thub/client.json        # "type": "sw", coordinatorUrl, joinKey
+    sudo systemctl enable --now thub-client@client
+    # a private registry for DUT images? log in once, as the Client's user:
+    docker login registry.lab.local:5000
+  p.small.
+    To scale out, clone the VM template. In the clone, #[strong before its first start], run
+    #[code rm -f ~/var/lib/thub/client/*/.client-id ~/var/lib/thub/client/*.token] and give it its own #[code name].
+    Otherwise both VMs register as the same resource.
+  +code('A typical SW job').
+    thub run --type sw \
+      --docker-image registry.lab.local:5000/dut-emulator:2026.08 \
+      --git-repo git@github.com:yourorg/firmware-tests.git main \
+      --command 'make test DUT="$THUB_DUT_HOST"' --wait
+
+  h3.h6 Checklist for any Client machine
+  ul.small.mb-0
+    li Correct time (NTP). Timestamps are anchored to the Coordinator's clock, but TLS needs a sane clock.
+    li Outbound HTTPS to the Coordinator; test it with #[code curl -sI #{coordinatorUrl}/login].
+    li The Client's service user has SSH keys and git credentials for private repos (#[a(href="#git") Git repositories]) and Docker logins for private registries (#[a(href="#docker") Docker registry]).
+    li Under systemd, the service can only write to its state directory. Jobs write to #[code $THUB_WORK_DIR], not to #[code ~].
+    li Optional: a nightly reboot from the resource card's #[strong Reboot] tab (cron, host-local time). It waits for running jobs.

package/views/help/_client-setup.pug

@@ -0,0 +1,122 @@
++section('client-setup', 'Client setup', 'motherboard')
+  p.
+    A Client (#[code thub-client]) is a daemon on a lab machine. One #[strong instance] owns one DUT slot. A machine with
+    several boards runs several instances (#[code dut0], #[code dut1], …), each with its own config file.
+    Clients register themselves with the shared join key; there's no admin step.
+
+  h3.h6 1. Install
+  +code('Lab machine, as the user the Client should run as (via sudo)').
+    # Node.js and HW tools (stlink-tools/openocd only for HW Clients)
+    sudo apt install -y nodejs npm stlink-tools openocd usbutils
+    # Docker: needed on SW Clients, and on HW Clients whose jobs use docker.
+    # Install it BEFORE thub-client so the service gets the docker group.
+    sudo apt install -y docker.io
+    sudo npm i -g @andrian.yablonskyy/thub-client
+  p.small.
+    This creates #[code ~/.config/thub/client.json] and #[code ~/var/lib/thub/client] for the user who ran
+    #[code sudo], and installs the #[code thub-client@.service] systemd unit running as that user, with the
+    #[code dialout], #[code plugdev] and #[code docker] groups. It also installs the root helpers that
+    apply self-updates and scheduled reboots.
+
+  h3.h6 2. Configure and start
+  .row.g-3
+    .col-md-6
+      +code('SW Client — ~/.config/thub/client.json').
+        {
+          "coordinatorUrl": "#{coordinatorUrl}",
+          "name": "lab-sw-01",
+          "type": "sw",
+          "labels": [],
+          "groups": [],
+          "joinKey": "<the Coordinator's clientJoinKey>",
+          "varDir": "/home/thub/var/lib/thub/client"
+        }
+    .col-md-6
+      +code('HW Client — ~/.config/thub/client.json').
+        {
+          "coordinatorUrl": "#{coordinatorUrl}",
+          "name": "lab-hw-01",
+          "type": "hw",
+          "labels": ["board:nucleo-f401re", "uart", "stlink"],
+          "groups": ["<group id>"],
+          "joinKey": "<the Coordinator's clientJoinKey>",
+          "varDir": "/home/thub/var/lib/thub/client",
+          "hw-devices": {
+            "stlinks": [{ "index": 1, "devpath": "3.3.4.3.1" }],
+            "uarts":   [{ "index": 1, "devpath": "3.3.3.2", "baudRate": 115200 }],
+            "usbs":    [{ "index": 1, "devpath": "3.2.4" }]
+          }
+        }
+  +code('Start it and follow the log').
+    sudo systemctl enable --now thub-client@client
+    journalctl -u thub-client@client -f
+
+  h3.h6 Config reference
+  .table-responsive
+    table.table.table-sm.small
+      thead
+        tr
+          th Field
+          th Required
+          th Meaning
+      tbody
+        tr
+          td: code coordinatorUrl
+          td Yes
+          td The Coordinator's #[code publicUrl].
+        tr
+          td: code type
+          td Yes
+          td #[code hw] (physical DUT) or #[code sw] (DUT image in Docker).
+        tr
+          td: code joinKey
+          td Yes
+          td Must equal the Coordinator's #[code clientJoinKey]. Or set #[code THUB_CLIENT_JOIN_KEY].
+        tr
+          td: code name
+          td No
+          td Resource name. Under systemd, the instance name (#[code thub-client@dut1] → #[code dut1]) is used unless an admin renames it on the dashboard.
+        tr
+          td: code labels
+          td No
+          td Matched against a job's #[code --board]/#[code --label]. Use #[code board:<name>] for the board.
+        tr
+          td: code groups
+          td No
+          td Group ids (from #[a(href="/groups") Groups]) this Client belongs to, for #[code thub run --group].
+        tr
+          td: code varDir
+          td No
+          td State directory: tokens, the client id, job workspaces, sockets. Keep the installer's default under systemd.
+        tr
+          td: code hw-devices.stlinks / uarts / usbs
+          td HW
+          td Up to 8 of each. An entry is a udev index #[code N] (→ #[code /dev/thub/dut<N>-stlink|uart|usb]), a path, or an object with #[code index]/#[code path], #[code devpath] (USB port), #[code serial] (ST-Link) and #[code baudRate] (UART, default 115200).
+        tr
+          td: code heartbeatIntervalSec / longPollWaitSec
+          td No
+          td 10 s / 30 s by default.
+        tr
+          td: code clientId
+          td No
+          td An explicit identity UUID (or #[code THUB_CLIENT_ID]). Normally generated once and kept in #[code .client-id].
+  p.small.
+    SW Clients have no settings of their own: they run whatever DUT image a job brings (#[code --docker-image]).
+    Admins can also edit an HW Client's devices from its resource card (#[strong ST-Link | UART | DUT USB]
+    tabs). #[strong Connected USB devices → Import to config] fills them from the host's #[code lsusb].
+
+  h3.h6 Several DUT slots on one machine
+  +code('One instance per slot').
+    thub-client register --name dut1 --type hw    # creates ~/.config/thub/dut1.json, starts thub-client@dut1
+    nano ~/.config/thub/dut1.json                 # set that slot's hw-devices
+    sudo systemctl restart thub-client@dut1
+    thub-client deregister --name dut1            # when the slot goes away
+
+  h3.h6 Controlling a Client
+  +code('As the Client\'s user (not with sudo)').
+    thub-client status
+    thub-client lock --reason "debugging I2C"     # BUSY (local): nothing gets scheduled here
+    thub-client unlock
+    thub-client restart
+    thub-client --config ~/.config/thub/dut1.json status    # a specific instance
+    thub-client udev --print                                # the udev rules this config generates

package/views/help/_coordinator.pug

@@ -0,0 +1,137 @@
++section('coordinator', 'Coordinator setup', 'hdd-network')
+  p.
+    One Coordinator serves the whole network. It's a single Node.js process with SQLite, which is
+    enough for tens of Clients and hundreds of jobs a day. Run it on a small Linux VM (Ubuntu recommended)
+    with Node.js 20+ (24 LTS recommended), reachable over HTTPS by the Agents and Clients.
+
+  h3.h6 1. Install as a systemd service
+  +code('Coordinator host').
+    sudo apt install -y nodejs npm
+    sudo npm i -g @andrian.yablonskyy/thub-coordinator
+  p.small.
+    #[code sudo npm i -g] does the whole setup for the user who ran #[code sudo]. It creates
+    #[code ~/.config/thub/coordinator.json] (with a random #[code sessionSecret]) and
+    #[code ~/var/lib/thub] (database, avatars). It installs, enables and starts
+    #[code thub-coordinator.service], plus the root helper behind the navbar's #[strong Update app] button.
+
+  h3.h6 2. Configure
+  p.small.
+    Edit #[code ~/.config/thub/coordinator.json], then #[code sudo systemctl restart thub-coordinator].
+    Logs: #[code journalctl -u thub-coordinator -f].
+  +code('~/.config/thub/coordinator.json').
+    {
+      "listen": "127.0.0.1:8080",
+      "publicUrl": "#{coordinatorUrl}",
+      "trustProxy": "loopback",
+      "dataDir": "/home/thub/var/lib/thub",
+      "sessionSecret": "<long random string>",
+      "session": { "secureCookie": "auto" },
+      "clientJoinKey": "<output of: thub-admin join-key generate>",
+      "heartbeat": { "intervalSec": 10, "missedLimit": 3, "sweepIntervalSec": 5 },
+      "scheduler": { "assignAckTimeoutSec": 15, "requeueOnLost": true, "maxQueuedPerAgent": 20, "tickIntervalSec": 10 },
+      "jobs": { "defaultTimeoutSec": 1800, "maxTimeoutSec": 14400 },
+      "retention": { "jobRetention": "forever" },
+      "updates": { "checkIntervalMin": 15, "registry": null }
+    }
+  .table-responsive
+    table.table.table-sm.small
+      thead
+        tr
+          th Field
+          th Meaning
+      tbody
+        tr
+          td: code listen
+          td Address the Node.js process binds to. Keep it on #[code 127.0.0.1] behind a reverse proxy.
+        tr
+          td: code publicUrl
+          td The URL Agents, Clients and job links use, e.g. #[code https://thub.example.com].
+        tr
+          td: code trustProxy
+          td Which proxies' #[code X-Forwarded-For] to trust for a Client's external address: #[code loopback] (default), a CIDR such as #[code "10.0.0.0/8"], a hop count, or #[code false].
+        tr
+          td: code sessionSecret
+          td Signs dashboard session cookies. Keep it secret and never use the #[code change-me-…] placeholder.
+        tr
+          td: code session.secureCookie
+          td #[code "auto"] (default): the session cookie is Secure (HTTPS-only) whenever #[code publicUrl] is https://. #[code true]/#[code false] force it. Sessions are stored in the database and survive restarts.
+        tr
+          td: code clientJoinKey
+          td The shared secret Clients self-register with. Unset or #[code null] turns registration off (#[code 503]).
+        tr
+          td: code heartbeat.*
+          td Clients heartbeat every #[code intervalSec]. After #[code missedLimit] misses a resource goes #[code OUT_OF_SERVICE] and its job becomes #[code LOST].
+        tr
+          td: code scheduler.*
+          td #[code assignAckTimeoutSec]: how long an assignment waits for the Client to accept. #[code requeueOnLost]: retry a #[code LOST] job once. #[code maxQueuedPerAgent]: queue limit per agent.
+        tr
+          td: code jobs.*
+          td Default and maximum job timeout, in seconds.
+        tr
+          td: code retention.*
+          td #[code jobRetention]: #[code 1w], #[code 2w], #[code 1m], #[code 3m], #[code 6m] or #[code forever]. Older finished jobs and their logs are deleted hourly.
+        tr
+          td: code updates.*
+          td How often to check npm for new versions (#[code 0] turns the periodic check off), and an optional private registry.
+  p.small.
+    Resolution order: #[code THUB_COORDINATOR_CONFIG] (a path) → #[code ~/.config/thub/coordinator.json] → the bundled
+    default. These environment variables override the file: #[code THUB_LISTEN], #[code THUB_PUBLIC_URL],
+    #[code THUB_DATA_DIR], #[code THUB_SESSION_SECRET] and #[code THUB_CLIENT_JOIN_KEY].
+
+  h3.h6 3. HTTPS reverse proxy
+  p.small.
+    Expose only port 443. Log streams use Server-Sent Events, so the proxy must not buffer responses.
+  .row.g-3
+    .col-md-6
+      +code('Caddyfile').
+        thub.example.com {
+          reverse_proxy 127.0.0.1:8080 {
+            flush_interval -1
+          }
+        }
+    .col-md-6
+      +code('nginx').
+        location / {
+          proxy_pass http://127.0.0.1:8080;
+          proxy_set_header Host $host;
+          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+          proxy_set_header X-Forwarded-Proto $scheme;
+          proxy_http_version 1.1;
+          proxy_buffering off;          # SSE log streams
+          proxy_read_timeout 1h;
+          client_max_body_size 10m;     # log batches, avatars
+        }
+
+  h3.h6 4. Users, agents and the join key
+  p.small.
+    #[code thub-admin] works directly on the database. Run it on the Coordinator host as the service user.
+  +code('Coordinator host').
+    thub-admin create-admin alice 's3cret' --role admin     # or --role viewer (read-only dashboard)
+    thub-admin join-key generate                            # → clientJoinKey here, joinKey on every Client
+    thub-admin agent add ci-firmware --kind ci              # CI token: job ids A-00001…
+    thub-admin agent add alice-laptop --kind cli            # developer token: job ids M-00001…
+    thub-admin group add ci-nightly --comment "nightly pool" # → a group id for thub run --group
+    thub-admin resource maintenance <resourceId> --on
+    thub-admin jobs reset --yes                             # cancel every active job
+    thub-admin jobs clean --yes --before "01/09/2026 00:00:00"
+  +note('warning').
+    Forgot the admin password? Start the Coordinator once with #[code THUB_BOOTSTRAP_ADMIN_PASSWORD=…]
+    (and optionally #[code THUB_BOOTSTRAP_ADMIN_USER], default #[code admin]). The password is reset on
+    #[em every] start while the variable is set, so unset it once you're signed in again.
+
+  h3.h6 Running from a checkout / DEV mode
+  +code('Repository checkout').
+    git clone --recurse-submodules git@github.com:andrianyablonskyy/thub.git && cd thub && npm install
+    THUB_BOOTSTRAP_ADMIN_PASSWORD=admin ./bin/coordinator
+    # Dashboard without hardware: virtual agent, two virtual Clients and demo jobs
+    DEV_MODE=1 THUB_BOOTSTRAP_ADMIN_PASSWORD=admin npm run coordinator
+  p.small.text-body-secondary.
+    In DEV mode the agent token is #[code agt_dev-virtual-agent-token], which is public. Never set
+    #[code DEV_MODE] on a real Coordinator.
+
+  h3.h6 Updates
+  p.small.mb-0.
+    The Coordinator checks npm for new Coordinator, Agent and Client versions. Admins update the Coordinator
+    with #[strong Update app] in the navbar, and Agents and Clients from the #[a(href="/admin/agents") Agents]
+    and #[a(href="/resources") Resources] pages. Clients install an update only between jobs.
+    Manual alternatives: #[code thub-admin self-update], #[code thub self-update] and #[code thub-client self-update].