@andrian.yablonskyy/thub-coordinator 1.1.12 → 1.1.14

package/views/help/_agent-cli.pug

@@ -23,20 +23,15 @@
         ['--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'"],
+        ['--command <string>', 'Required. Run with sh -c in the work directory. Exit code 0 = PASSED. It clones repositories and runs containers itself (see Using git / Using Docker).', "--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'],
+        ['--suite <name>', 'Passed as JOB_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']
+        ['--env <vars>', 'NAME=value[,NAME=value] for the command (repeatable): how data and secrets reach the job (git tokens, registry passwords). --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']
       ] },
@@ -74,12 +69,13 @@
   +code('Flash and test a board, fail CI on failure').
     thub run --type hw --label 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 "$@"' \
+      --env GH_TOKEN \
+      --command 'git clone --depth 1 --branch v1.4.0 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
+                 st-flash --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 --label board:nucleo-f401re --client lab-hw-01 --user "$USER" \
-      --download-file "$IMAGE_URL" --git-repo "$TESTS_REPO" --command ./ci/test.sh
+  +code('Reproduce a failure on the exact bench (the job carries your username)').
+    thub run --type hw --label board:nucleo-f401re --client lab-hw-01 \
+      --download-file "$IMAGE_URL" --env GH_TOKEN --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@$TESTS_REPO" src && cd src && ./ci/test.sh'
     # Ctrl-C detaches; the job keeps running. Re-attach:
     thub status M-00126
   +code('Verify a download before using it').
@@ -87,14 +83,14 @@
       --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" \
+    thub run --type sw \
       --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 \
+    thub run --type sw --download-file https://example.invalid/app.bin \
       --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)
+    JOB=$(thub run --type sw --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').

package/views/help/_agent-setup.pug

@@ -42,7 +42,6 @@
   +code('Save the settings once').
     thub config set url   #{coordinatorUrl}
     thub config set key   thk_…
-    thub config set user  "Your Name"      # optional: job owner label
   p.small.
     These are saved in #[code ~/.config/thub/agent.json]. Which runner group your jobs run in isn't an Agent
     setting: an admin or maintainer sets it for your user on the dashboard (#[code thub whoami] shows it). Order of precedence: flags (#[code --url], #[code --key]) →
@@ -59,9 +58,6 @@
       tr
         td: code THUB_KEY
         td Your access key, or a CI token in a pipeline. Keep it in your CI's secret store. (#[code THUB_TOKEN], #[code --token] and a saved #[code token] still work: the old names.)
-      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

package/views/help/_ci.pug

@@ -33,8 +33,9 @@
               npx -y @andrian.yablonskyy/thub-agent run \
                 --type hw --label 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' \
+                --env GH_TOKEN="${{ secrets.TESTS_READ_TOKEN }}",SHA="$GITHUB_SHA",REPO="$GITHUB_REPOSITORY" \
+                --command 'git init -q src && cd src && git fetch -q --depth 1 "https://x-access-token:$GH_TOKEN@github.com/$REPO.git" "$SHA" && git checkout -q FETCH_HEAD &&
+                           st-flash --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

package/views/help/_client-machines.pug

@@ -26,8 +26,8 @@
         .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 Whatever your jobs' commands use: git, Docker Engine (#[code docker.io]; install it before the Client so its service user gets the #[code docker] group), an emulator. The Client itself needs none of them.
+            li 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.
 
@@ -52,8 +52,9 @@
   +code('A typical HW job').
     thub run --type hw --label 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' \
+      --env GH_TOKEN \
+      --command 'git clone --depth 1 --branch v1.4.0 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
+                 st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh' \
       --wait
 
   +note('warning').
@@ -62,26 +63,25 @@
 
   h3.h6 Preparing an SW machine (real or virtual)
   +code('SW machine / VM').
-    sudo apt install -y nodejs npm docker.io
+    sudo apt install -y nodejs npm         # + git, docker.io, … if your jobs' commands use them
     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 runner.
   +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
+      --env GH_TOKEN --env DOCKER_PASSWORD \
+      --command 'git clone --depth 1 "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
+                 echo "$DOCKER_PASSWORD" | docker login registry.lab.local:5000 -u ci --password-stdin &&
+                 docker run --rm --user "$(id -u):$(id -g)" -v "$THUB_WORK_DIR/src:/work" -w /work registry.lab.local:5000/dut-emulator:2026.08 make test' --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 Whatever tools your jobs' commands use (git, docker, a flasher) are installed. Their credentials come with each job as #[code --env] (#[a(href="#git") Using git], #[a(href="#docker") Using Docker]), not from the host.
     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 runner card's #[strong Reboot] tab (cron, host-local time). It waits for running jobs.

package/views/help/_client-setup.pug

@@ -8,8 +8,8 @@
   +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.
+    # Optional — the Client doesn't need it. Only if your jobs' commands run 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.
@@ -66,7 +66,7 @@
         tr
           td: code type
           td Yes
-          td #[code hw] (physical DUT) or #[code sw] (DUT image in Docker).
+          td #[code hw] (physical DUT) or #[code sw] (software-only: jobs run just their command).
         tr
           td: code joinKey
           td Yes
@@ -100,14 +100,14 @@
           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]).
+    SW Clients have no settings of their own: a job's #[code --command] starts whatever it needs (a container, an emulator).
     Admins can also edit an HW Client's devices from its runner card (#[strong ST-Link | UART | DUT USB]
     tabs). The tabs show the config the Client runs, as it reported it at its last start, or a saved
     change it hasn't applied yet. #[strong USB devices → Import to config] fills them from the host's #[code lsusb].
     The card's #[strong Export] and #[strong Import] icons download a Client's config file (never its
     #[code joinKey]) and apply one to it. An older HW Client takes only the file's #[code hw-devices].
-    There's no ST-Link serial field: the job's #[code --command] picks the probe
-    (#[code $THUB_DUT_STLINK_<n>]), and the Client reads each serial from its udev symlink.
+    There's no ST-Link serial field: the job's #[code --command] picks the probe (#[code st-flash] alone uses the
+    only one; with several, #[code st-flash --serial] with a serial from #[code st-info --probe]).
 
   h3.h6 Several DUT slots on one machine
   +code('One instance per slot').

package/views/help/_docker.pug

@@ -1,99 +1,23 @@
-+section('docker', 'Docker registry integration', 'box-seam')
++section('docker', 'Using Docker in a job', 'box-seam')
   p.
-    A job can use Docker in two different ways. Keep them apart, because they log in and run differently:
-  .row.g-3.mb-3
-    .col-md-6
-      .card.h-100
-        .card-body.small
-          h3.h6 #[code --docker-image]: the DUT
-          p.mb-0.
-            SW jobs only. The Client pulls the image and runs it as the job's #[strong DUT container]
-            (an emulator the tests talk to), sandboxed, next to your command. The pull uses the
-            #[strong Client host's] Docker login, made once by the service user.
-    .col-md-6
-      .card.h-100
-        .card-body.small
-          h3.h6 #[code docker …] inside #[code --command]
-          p.mb-0.
-            Any job type, on a host with Docker. Your command logs in, pulls and runs containers
-            itself, e.g. to run the tests #[em inside] an image. Credentials come from the job
-            (#[code --env]) and are scoped to the job.
+    The Client doesn't pull images or start containers itself and doesn't need Docker. A job that needs a container runs
+    #[code docker] in its #[code --command], on a Client host that has Docker (the runner card's #[strong Capabilities] tab says
+    whether it does). Registry credentials come from the job as #[code --env]: masked everywhere, dropped when the job ends.
 
-  h3.h6 Log in to a registry on the Client host (for --docker-image)
+  h3.h6 Log in, pull and run, credentials scoped to the job
   p.small.
-    #[code --docker-image] is pulled with #[code docker pull] as the Client's service user, from the registry the reference names
-    (Docker Hub for a short name such as #[code python:3.14]). Log in once per host, as that user:
-  +code('Client host').
-    # the user that runs thub-client (the one who ran sudo npm i -g), e.g. thub:
-    sudo -u thub docker login registry.lab.local:5000
-    sudo -u thub docker login ghcr.io -u <github-user>        # password: a PAT with read:packages
-    sudo -u thub docker pull registry.lab.local:5000/dut-emulator:2026.08   # check it works
-  p.small.
-    A plain-HTTP registry must be listed in the Docker daemon's #[code insecure-registries]:
-  +code('/etc/docker/daemon.json').
-    { "insecure-registries": ["registry.lab.local:5000"] }
-  p.small.
-    Then run #[code sudo systemctl restart docker]. An image that can't be pulled ends the job as #[code ERROR]
-    during #[em prepare], naming the registry and Docker's reason. An image already on the host isn't pulled again.
-
-  h3.h6 How the Client starts the DUT container
-  p.small.
-    You don't pass #[code docker run] parameters for the DUT. The Client always starts it like this (image default command,
-    sandboxed), and removes it and its network when the job ends:
-  +code('What the Client runs (equivalent)').
-    docker pull registry.lab.local:5000/dut-emulator:2026.08
-    docker network create --driver bridge thub-job-<jobId>
-    docker run -d --name thub-<jobId> --network thub-job-<jobId> \
-      --memory 2g --cpus 2 --read-only \
-      -v <workDir>/<jobId>/downloads:/downloads:ro \
-      -p 127.0.0.1::5555 registry.lab.local:5000/dut-emulator:2026.08
-  ul.small
-    li The image must #[strong start the DUT by itself] (its #[code CMD]/#[code ENTRYPOINT]) and should listen on port #[strong 5555].
-    li The job's #[code --download-file] files are mounted read-only at #[code /downloads] (e.g. the firmware to emulate).
-    li The command reaches it at #[code $THUB_DUT_HOST] (#[code 127.0.0.1:<port>]) and by name as #[code $THUB_DUT_CONTAINER].
-    li Its output is shipped as the #[code emulator] log stream. Its root filesystem is read-only: don't install or clone into it.
-    li #[code thub run --dry-run] prints the exact docker commands a job would run, without running anything.
-
-  h3.h6 Execute commands in the DUT container
-  +code('SW job: talk to the DUT').
-    thub run --type sw \
-      --docker-image registry.lab.local:5000/dut-emulator:2026.08 \
-      --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.elf \
-      --command 'docker exec "$THUB_DUT_CONTAINER" /opt/emu/status &&
-                 docker logs "$THUB_DUT_CONTAINER" | tail -n 20 &&
-                 ./ci/test.sh --dut "$THUB_DUT_HOST"' \
-      --wait
-
-  h3.h6 Log in and pull inside a job (credentials scoped to the job)
-  p.small.
-    Pass the credentials as #[code --env] (masked everywhere, dropped when the job ends). Set #[code DOCKER_CONFIG] to the
-    job's work directory so the login is deleted with the workspace instead of staying in the service user's
-    #[code ~/.docker] for every later job:
+    Point #[code DOCKER_CONFIG] at the job's directory so the login is deleted with the job instead of staying in the
+    service user's #[code ~/.docker] for every later job:
   +code('Any job type').
     export DOCKER_PASSWORD=…        # from your CI secret store, never on the command line
-    thub run --type hw \
-      --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
-      --command 'export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
-                 echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
-                 docker pull "$DOCKER_REGISTRY/team/test-runner:1.4"' \
-      --wait
-
-  h3.h6 Run the tests inside a container (docker run parameters)
-  p.small.
-    The command always starts on the Client host, in #[code $THUB_WORK_DIR] (the #[code --git-repo] checkout). Mount it,
-    hand over the variables the tests need with #[code -e NAME], and use #[code --rm]:
-  +code('Tests in an image').
     thub run --type sw \
       --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
       --env TARGET=staging \
-      --git-repo git@github.com:yourorg/web-ui-tests.git main \
-      --command 'export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
-                 echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
-                 docker run --rm \
-                   -v "$THUB_WORK_DIR:/work" -w /work \
-                   -e TARGET -e THUB_SUITE -e THUB_JOB_ID \
-                   --network host \
-                   "$DOCKER_REGISTRY/python:3.14" ./run-tests.sh --junit results/junit.xml' \
+      --command 'echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
+                 docker run --rm --user "$(id -u):$(id -g)" \
+                   -v "$THUB_WORK_DIR/src:/work" -w /work \
+                   -e TARGET -e JOB_SUITE -e THUB_JOB_ID \
+                   "$DOCKER_REGISTRY/team/test-runner:1.4" ./run-tests.sh --junit results/junit.xml' \
       --wait
   table.table.table-sm.small
     thead
@@ -105,20 +29,61 @@
         td: code --rm
         td Removes the container when the tests end.
       tr
-        td: code -v "$THUB_WORK_DIR:/work" -w /work
-        td The checkout and downloads, and the #[code results/] and #[code artifacts/] folders, where the Client reads JUnit XML for the test counts.
+        td: code -v "$THUB_WORK_DIR/src:/work" -w /work
+        td Only the clone (#[code src/]), not the job directory, which holds the registry login in #[code .docker/]. The Client reads JUnit XML from #[code src/results/] or #[code src/artifacts/] for the test counts.
       tr
         td: code -e NAME
         td Passes a job variable (#[code --env], #[code THUB_*], #[code JOB_*]) into the container.
-      tr
-        td: code --network host
-        td Lets the container reach the DUT at #[code $THUB_DUT_HOST] (#[code 127.0.0.1:<port>]).
-      tr
-        td: code --device /dev/thub/dut1-uart
-        td HW: gives the container the DUT's UART (#[code "$THUB_DUT_UART"]). Use #[code --privileged] only if you must.
       tr
         td: code --user "$(id -u):$(id -g)"
         td Files written to #[code /work] stay owned by the Client user, so the workspace can be cleaned up.
+      tr
+        td: code --device /dev/thub/dut1-uart
+        td HW: gives the container the DUT's UART (#[code /dev/thub/dut1-uart]). Use #[code --privileged] only if you must.
+
+  h3.h6 Clone and test inside a container, with a deploy key and a registry login from the job
+  p.small.
+    Everything comes from the Agent as #[code --env]: the registry and its credentials, and the private key the
+    container clones with. Nothing is set up on the Client host beforehand.
+  +code('Reference example').
+    # In CI, from its secret store — never typed on the command line:
+    export THUB_KEY=…                              # a CI token (dashboard → CI tokens)
+    export DOCKER_PASSWORD=…                       # the registry password
+    export GIT_KEY="$(cat ~/.ssh/thub_deploy)"     # a private deploy key with read access to the repository
+    
+    thub run --type sw \
+      --env DOCKER_REGISTRY=registry.lab:5000,DOCKER_USERNAME=ci-reader \
+      --env DOCKER_PASSWORD --env GIT_KEY \
+      --command 'echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" --username "$DOCKER_USERNAME" --password-stdin &&
+                 mkdir -p "$THUB_WORK_DIR/src" &&
+                 docker run --rm -e GIT_KEY -e HOME=/tmp --user "$(id -u):$(id -g)" \
+                   -v "$THUB_WORK_DIR/src:/work" -w /work --entrypoint sh alpine/git -c "
+                   eval \$(ssh-agent -s) > /dev/null &&
+                   printf \"%s\n\" \"\$GIT_KEY\" | ssh-add - &&
+                   GIT_SSH_COMMAND=\"ssh -o StrictHostKeyChecking=accept-new\" git clone --depth 1 git@bitbucket.org:yourorg/web-ui-tests.git . &&
+                   ./run-tests.sh"' \
+      --wait
+  ul.small
+    li Plain values go as #[code --env NAME=value]. Secrets go as #[code --env NAME] alone: the Agent takes the value from its own environment, so it never appears on the command line, in shell history or in CI logs. A multi-line value, such as the key, arrives intact.
+    li The Client sets #[code DOCKER_CONFIG=$THUB_WORK_DIR/.docker]: the registry login lands in the job's directory, deleted with the job. Only #[code src/] is mounted into the container, so the login isn't visible in it.
+    li #[code -e GIT_KEY] hands the key to the container. #[code --entrypoint sh] is needed because #[code alpine/git]'s own entrypoint is #[code git]. #[code --user "$(id -u):$(id -g)"] (with #[code HOME=/tmp]) keeps the clone owned by the Client user, so it can be deleted with the job; #[code mkdir -p] first so Docker doesn't create #[code src/] as root.
+    li In the inner script, #[code \$] is escaped, so the #[strong container] expands the variables, not the Client's shell. #[code ssh-agent] holds the key in memory: it's never written to a file. #[code accept-new] trusts the git server's host key on first use.
+    li #[code alpine/git] comes from Docker Hub. The #[code docker login] is for private images such as #[code $DOCKER_REGISTRY/team/test-runner:1.4].
+    li Never #[code echo] a secret: the command's output is the job log, which is stored and visible.
+
+  h3.h6 An emulator as the DUT
+  p.small.
+    Start it in the background in the command, talk to it, and stop it whatever the result:
+  +code('SW job with an emulator container').
+    thub run --type sw \
+      --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.elf \
+      --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
+      --command 'echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
+                 dut="thub-$THUB_JOB_ID" && trap "docker rm -f $dut >/dev/null" EXIT &&
+                 docker run -d --name "$dut" -p 127.0.0.1:5555:5555 -v "$THUB_DOWNLOADS_DIR:/downloads:ro" \
+                   "$DOCKER_REGISTRY/dut-emulator:2026.08" &&
+                 ./ci/test.sh --dut 127.0.0.1:5555' \
+      --wait
   +note('info').
-    Docker access is effectively root access on that host. The Client host must have Docker and the service user must be in the
-    #[code docker] group. The runner card's #[strong Capabilities] tab shows whether a Client can use Docker, and why not.
+    Docker access is effectively root access on that host. The service user needs the #[code docker] group: install Docker
+    before the Client (#[code sudo npm i -g …] adds the group), or re-run the install afterwards.

package/views/help/_env.pug

@@ -10,17 +10,11 @@
     const thubVars = [
       ['THUB_JOB_ID', 'The job id, e.g. M-00125'],
       ['THUB_ARTIFACTS_FILE', 'Where the command may list the artifacts it published elsewhere: a JSON array of {"name", "size", "link", "timestamp"}, shown on the job page'],
-      ['THUB_WORK_DIR', 'The directory the command runs in: the --git-repo checkout, else empty. JUnit XML in results/ or artifacts/ gives the test counts; deleted when the job ends'],
-      ['THUB_SUITE', '--suite (default: default)'],
-      ['THUB_GIT_COMMIT', 'The exact commit checked out for --git-repo'],
+      ['THUB_WORK_DIR', 'The job\'s directory (<client workDir>/<jobId>), where the command starts. Holds downloads/, the artifacts list and .docker/ (the job\'s DOCKER_CONFIG); clone into a folder of your own, e.g. src/. JUnit XML in results/ or artifacts/ gives the test counts; deleted when the job ends'],
+      ['DOCKER_CONFIG', '$THUB_WORK_DIR/.docker — so a docker login stays with the job and is deleted with it (unless --env sets DOCKER_CONFIG)'],
       ['THUB_DOWNLOADS_DIR', 'Where the --download-file files are'],
       ['THUB_DOWNLOADS / THUB_DOWNLOAD_<n>', 'Local paths of the downloads: all, one per line / each one'],
       ['THUB_META_<KEY>', '--meta values; camelCase keys become SNAKE_CASE (ciJobId → THUB_META_CI_JOB_ID)'],
-      ['THUB_DUT_STLINK / _<n>', 'HW: ST-Link serials (device path if the serial couldn\'t be read); unsuffixed = the first'],
-      ['THUB_DUT_UART / _<n>', 'HW: UART device paths (/dev/thub/dut<N>-uart); unsuffixed = the first'],
-      ['THUB_DUT_USB / _<n>', 'HW: DUT USB device paths'],
-      ['THUB_DUT_HOST', 'SW with --docker-image: 127.0.0.1:<port> of the DUT container\'s port 5555'],
-      ['THUB_DUT_CONTAINER', 'SW with --docker-image: the DUT container\'s name (docker exec / docker logs)']
     ]
   .table-responsive
     table.table.table-sm.small
@@ -38,14 +32,9 @@
       ['JOB_LABEL / JOB_LABEL_<n>', '--label', 'all labels, comma-separated / each'],
       ['JOB_GROUP', '(dashboard)', 'the submitting agent\'s group, if it has one'],
       ['JOB_CLIENT', '--client', 'this Client\'s name'],
-      ['JOB_USER', '--user', 'as given'],
+      ['JOB_USER', '(your key)', 'the submitting user\'s username, or the CI token\'s name'],
       ['JOB_COMMAND', '--command', 'the command itself'],
       ['JOB_DOWNLOAD_FILE / _<n>', '--download-file', 'the URLs (the local files are THUB_DOWNLOAD_<n>)'],
-      ['JOB_DOCKER_IMAGE', '--docker-image', 'the image reference'],
-      ['JOB_GIT_REPO_URL', '--git-repo <url>', 'the repository URL'],
-      ['JOB_GIT_BRANCH', '--git-repo <url> <ref>', 'branch, tag or commit as given (unset = default branch)'],
-      ['JOB_GIT_DEPTH', '--depth', 'commits fetched (1 by default, 0 = full)'],
-      ['JOB_GIT_OPTIONS', '--git-options', 'as given'],
       ['JOB_SUITE', '--suite', 'as given, default when not'],
       ['JOB_ARG / JOB_ARG_<n>', '--arg', 'all, space-separated / each (also "$@")'],
       ['JOB_TIMEOUT', '--timeout', 'seconds'],
@@ -74,8 +63,8 @@
   ul.small
     li #[code --env NAME=value[,NAME=value]], repeatable. A comma starts a new variable only when #[code NAME=] follows it, so values may contain commas.
     li #[code --env NAME] alone takes the value from the Agent's environment. That keeps secrets off the command line, out of shell history and out of CI logs.
-    li Any names except #[code THUB_*], #[code JOB_*], #[code GIT_TERMINAL_PROMPT] and #[code GIT_ALLOW_PROTOCOL].
-    li They apply to every command the Client runs for the job: the #[code --git-repo] git commands and #[code --command].
+    li Any names except #[code THUB_*] and #[code JOB_*].
+    li They're how every piece of data and every secret reaches the job: a git token for its #[code git clone], a registry password for its #[code docker login], an API key for its tests.
     li
       | Every value is treated as a secret. It's sent only to the Client running the job, shown as #[code ***] by the API,
       | #[code thub status --json] and #[code --dry-run], and wiped from the Coordinator's database when the job ends.
@@ -88,40 +77,40 @@
   +code('ci/test.sh (shell)').
     #!/bin/sh
     set -eu
-    echo "Job $THUB_JOB_ID on $(hostname), suite ${THUB_SUITE}, commit ${THUB_GIT_COMMIT:-n/a}"
+    echo "Job $THUB_JOB_ID on $(hostname), suite ${JOB_SUITE}"
 
     # optional parameters with defaults
     TARGET="${TARGET:-staging}"
-    BRANCH="${JOB_GIT_BRANCH:-main}"
+    BRANCH="${BRANCH:-main}"          # from --env BRANCH=…
 
     # every downloaded file
     printf '%s\n' "$THUB_DOWNLOADS" | while read -r f; do echo "downloaded: $f"; done
 
     # HW: flash through the first ST-Link, talk to the second UART
-    st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000
-    python3 -m pytest tests/ --uart "${THUB_DUT_UART_2:-$THUB_DUT_UART}" --junitxml=results/junit.xml
+    st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000
+    python3 -m pytest tests/ --uart "/dev/thub/dut2-uart" --junitxml=results/junit.xml
 
     # CI metadata passed with --meta ciJobId=… / --meta sha=…
     echo "CI run ${THUB_META_CI_JOB_ID:-local}, sha ${THUB_META_SHA:-unknown}"
   +code('conftest.py (Python)').
-    import os
+    import glob, os
 
-    DUT_HOST  = os.environ.get("THUB_DUT_HOST", "127.0.0.1:5555")   # SW DUT container
-    UARTS     = [v for k, v in sorted(os.environ.items()) if k.startswith("THUB_DUT_UART_")]
+    UARTS     = sorted(glob.glob("/dev/thub/dut*-uart"))                # this Client's UARTs, by udev path
     FIRMWARE  = os.environ.get("THUB_DOWNLOAD_1")
-    RESULTS   = os.path.join(os.environ.get("THUB_WORK_DIR", "."), "results")
+    RESULTS   = "results"                                            # in the clone (src/results), where the tests run
     API_TOKEN = os.environ["API_TOKEN"]                              # from --env API_TOKEN
   +code('Into a container: -e NAME copies a variable from the job').
-    docker run --rm -v "$THUB_WORK_DIR:/work" -w /work \
-      -e THUB_JOB_ID -e THUB_SUITE -e TARGET -e API_TOKEN \
+    docker run --rm --user "$(id -u):$(id -g)" -v "$THUB_WORK_DIR/src:/work" -w /work \
+      -e THUB_JOB_ID -e JOB_SUITE -e TARGET -e API_TOKEN \
       python:3.14 ./run-tests.sh
   +code('Submitting the job that feeds these').
     export API_TOKEN=…
     thub run --type hw --label board:nucleo-f401re \
       --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
-      --git-repo git@github.com:yourorg/firmware-tests.git main \
-      --env TARGET=production --env API_TOKEN \
+      --env TARGET=production,BRANCH=main --env API_TOKEN --env GH_TOKEN \
       --meta ciJobId="$GITHUB_RUN_ID" --meta sha="$GITHUB_SHA" \
-      --suite smoke --command ./ci/test.sh --wait
+      --suite smoke \
+      --command 'git clone --depth 1 --branch "$BRANCH" "https://x-access-token:$GH_TOKEN@github.com/yourorg/firmware-tests.git" src && cd src &&
+                 ./ci/test.sh' --wait
   p.small.text-body-secondary.mb-0.
     Tip: #[code thub run … --dry-run] lists every variable the command would get on the chosen Client, with #[code --env] values as #[code ***].