RAM and new hardware are expensive. Your old PCs are not. Plug them back in and give them work.
lanq is a small .NET global tool that sends builds, tests, log analysis and headless coding-agent jobs to the other
computers you already own: the old desktop in the closet, the spare laptop, the small-form-factor box. Your old
machines can still help you get development done. All a worker needs is a LAN connection, SSH, git (or just tar, see
Transfer modes) and the toolchain for your jobs, and it joins
your queue. Your dev PC stays free for writing code. Even a PC too old or locked down to install git can help: SSH,
tar and your toolchain are enough.
dotnet tool install --global LanQueue # update later: dotnet tool update --global LanQueueNo .NET SDK? Each release also has a single-file native lanq for Windows, Linux (glibc 2.27 and later) and macOS,
and a Scoop manifest; see Install.
Setting up a pool for a team? docs/TEAM-QUICKSTART.md walks through one orchestrator
and a mix of Windows 10/11 and Linux workers, low-RAM micro PCs and overnight family PCs included, from lanq init to
the first job, with the ten most common errors and their fixes.
A 3-command taste (after you list your machines once in machines.yml, see Quick start):
lanq health # which machines are awake and free?
lanq run --needs dotnet,linux -- dotnet test -c Release # run on the least loaded match
lanq stats # how long did jobs take?For each job it checks which machines are awake and not busy, picks the least loaded one that has what the job
needs, ships your current git state (HEAD plus uncommitted changes) to a throw-away worktree over key-only SSH, runs
one allowlisted command, streams the log back, cleans up, and records how long it took. It is headless and
scriptable, it has no daemon and no server to install on the remote machines (just ssh, git or tar, and a shell), and it
sends nothing anywhere except to the hosts you list. There is no telemetry.
This is the author's first-hand account, not a benchmark. The author works on two projects (a .NET API and a web front end) from one dev PC. One overnight run put two heavy agent-driven build/test jobs, the local dev stack and a scheduled task on that single machine at the same time. The local API crashed, the front-end dev server broke, a task expected to take an hour or two took most of an afternoon, and the failures that night were machine load, not code defects.
The fix was organisational before it was technical: allow one heavy job at a time on the dev PC, and send builds
and tests to two spare machines on the LAN (a build box and a small-form-factor PC) over key-only SSH, so the dev PC
stays free for writing code and orchestrating. Along the way the author hit the usual remote-Windows traps (stale
incremental builds after file overlays, "Filename too long" in deep worktrees, quirks of running tests over SSH).
lanq is that routine turned into a tool.
lanq stats reads a local log of every job: per machine and per command the counts, median and p90 times, each
machine's speed factor, and how long a command's work and per-shard overhead are. There are no published measurements
yet, and this README makes no speed-up claim.
On the machine you run lanq from you need git and ssh/scp on the PATH. Remote machines need an SSH server
(Linux: sh; Windows: OpenSSH Server with PowerShell 5.1+) and either git (the default) or tar (with
transfer: archive). Then pick one of three ways to get lanq itself:
| Way | Needs | Upgrade |
|---|---|---|
| Native binary from GitHub Releases | nothing else | download the new one |
| Scoop (Windows) | Scoop | scoop update lanq |
| .NET tool from nuget.org | the .NET 10 SDK | dotnet tool update --global LanQueue |
From 0.5.0 each release has a single-file, ahead-of-time compiled lanq for five targets. Each archive holds lanq
(lanq.exe on Windows), LICENSE and THIRD-PARTY-NOTICES.txt; put lanq anywhere on your PATH.
| Asset | Runs on |
|---|---|
lanq-win-x64.zip |
Windows x64 (the Windows versions .NET 10 supports) |
lanq-win-arm64.zip |
Windows 11 on Arm64 |
lanq-linux-x64.tar.gz |
Linux x64 with glibc 2.27 or later (Ubuntu 18.04, Debian 10, RHEL 8 and newer) |
lanq-linux-arm64.tar.gz |
Linux Arm64 with glibc 2.27 or later (Raspberry Pi OS 64-bit, Ubuntu 18.04 and newer) |
lanq-osx-arm64.tar.gz |
macOS on Apple silicon |
The Linux binaries are linked against Microsoft's .NET 10 build sysroot (Ubuntu 18.04, glibc 2.27), not against the
build machine's newer glibc, and every release runs them inside an Ubuntu 18.04 container before publishing. glibc
2.27 is .NET 10's own floor; there is no musl (Alpine) or 32-bit build. On macOS, a file downloaded with a browser is
quarantined; xattr -d com.apple.quarantine lanq clears that (the binary is ad-hoc signed, not notarized).
# Linux x64 example: download, verify (see below), install
gh release download --repo jangolath/lanqueue --pattern 'lanq-linux-x64.tar.gz' --pattern SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
gh attestation verify lanq-linux-x64.tar.gz --repo jangolath/lanqueue
tar -xzf lanq-linux-x64.tar.gz lanq && install -D -m 755 lanq ~/.local/bin/lanq # ~/.local/bin must be on PATH (most distros add it at next login)
lanq --versionOn Windows, check the hash in PowerShell with (Get-FileHash lanq-win-x64.zip -Algorithm SHA256).Hash and compare it
with the line for that file in SHA256SUMS, or use gh attestation verify as above.
A native binary carries its own copy of the .NET runtime, so a .NET security fix reaches it only through a new
lanq release (see SECURITY.md). The .NET tool instead uses the runtime installed on your machine.
Every release attaches a Scoop manifest, lanq.json, that pins that release's zip URLs and SHA-256 hashes. There is
no bucket to add:
scoop install https://github.com/jangolath/lanqueue/releases/latest/download/lanq.json
scoop update lanq # laterScoop remembers the URL an app was installed from and reads the manifest from it again on scoop update and
scoop status, so because that URL always points at the latest release, scoop update lanq moves to new versions.
scoop search does not find lanq (it is in no bucket), and scoop update needs to reach GitHub. To stay on one
version, install from that release's URL instead, for example
https://github.com/jangolath/lanqueue/releases/download/v0.12.0/lanq.json. Scoop checks each zip against the hash in
the manifest; the manifest itself is covered by SHA256SUMS and the release's attestation. Release candidates
(tags such as v0.5.0-rc.1) are published as GitHub prereleases, which releases/latest never points at, so the
latest URL never installs one.
Requires the .NET 10 SDK.
dotnet tool install --global LanQueue
dotnet tool update --global LanQueue # later, to upgradePackage: nuget.org/packages/LanQueue. The tool package is framework-dependent (it runs on the .NET runtime you have) and behaves exactly like the native binary: both read the config through the same compile-time (source-generated) YAML and JSON code. Prefer to build it yourself? From a clone:
dotnet pack src/LanQueue -c Release -o ./nupkg
dotnet tool install --global --add-source ./nupkg LanQueueTo build a native binary yourself (needs the platform's C toolchain, see Native AOT prerequisites):
dotnet publish src/LanQueue -c Release -r linux-x64 -p:LanqNative=true -o ./nativeEvery release asset is covered by one SHA256SUMS file and by a GitHub build-provenance attestation (signed with the
release workflow's OIDC identity, logged in the public Sigstore transparency log). sha256sum --check proves a
download is intact; gh attestation verify also proves it was built from this repository by the release workflow:
gh release download v0.12.0 --repo jangolath/lanqueue
sha256sum --check SHA256SUMS
for f in *.zip *.tar.gz *.nupkg lanq.json SHA256SUMS; do gh attestation verify "$f" --repo jangolath/lanqueue; done
dotnet tool install --global --add-source . LanQueue --version 0.12.0 # the attested package, if you want the toolFrom 0.4.0 the .nupkg is attested; from 0.5.0 every asset is. The copy on nuget.org carries nuget.org's own
repository signature, so its bytes differ from the attested file; verify the GitHub Release asset. Dependencies are
pinned too: every project commits a packages.lock.json (the native build has its own, packages.native.lock.json),
CI restores in locked mode, and every GitHub Action and build container is pinned to a full SHA or digest.
Before your first job, each worker needs an SSH server, git (or only tar in archive mode) and the toolchain your jobs use; it does not need
GitHub access, Docker (unless your jobs use it) or lanqueue itself. Checklist and setup steps:
docs/WORKERS.md. No Linux machine? A Windows PC with Docker Desktop can run one in a container
(a Linux worker in Docker).
-
Write a starter config with
lanq init: it goes to the per-user file lanq reads without flags (~/.config/lanq/machines.yml, or$XDG_CONFIG_HOME/lanq/machines.yml; on Windows%APPDATA%\lanq\machines.yml), never into the current folder, and prints the path. Or copymachines.example.ymlthere, and edit it: the repository'smachines.example.ymlis only a template, and lanq never reads it. A config in the current directory is never picked up implicitly; for another file pass--config FILEor setLANQ_CONFIG(lanq initthen writes that file). -
Make sure key-based login works and the host key is already in
known_hosts. With a key loaded in ssh-agent (recommended, see Keeping your keys safe):ssh user@build-01.lan true. -
Check your setup and the fleet (
lanq doctor --remotealso checks each worker's tools; see Commands):$ lanq health build-01 OK load 0.12 cores 8 ram 15.6 GB disk free 180.4 GB mem free 9.8 GB (swap 2.0 GB) slots free 2/2 suited: heavy: full suites and large builds build-02 HOLD load 0.05 cores 4 ram 7.8 GB disk free 90.1 GB mem free 5.1 GB slots free 1/1 suited: medium: test shards and builds (outside allowed hours) build-03 DOWN build-03.lan refused the connection: its SSH server is not running, or a firewall rejects the ssh port (Windows: Start-Service sshd and Set-Service sshd -StartupType Automatic; Linux: sudo systemctl enable --now ssh) (ssh: ssh: connect to host build-03.lan port 22: Connection refused)Each line shows the machine's size (cores, total RAM, free/total slots, what it is suited for; see Sharding), and a machine that does not answer says what to fix, quoting ssh's own line.
-
Run something from inside a git repository:
lanq run --needs dotnet,linux --dir tests -- dotnet test -c ReleaseThe job's exit code becomes
lanq's exit code.--wait 120keeps retrying for up to 120 seconds when every machine is busy or on hold, and may wake a sleeping machine that has awake:setting as a last resort (--no-wakeprevents that; see Wake-on-LAN).--timeout 60stops the job after 60 minutes (default 240).--mem 4sends the job only to a machine that reports at least 4 GB of available memory.--fetch 'TestResults/**/*.trx'brings test results, coverage or build output back after the job (see Fetching results).lanq statssummarises your local job log.
Exit codes: the job's own code; 2 rejected by policy or bad arguments; 70 infrastructure error (SSH, git);
75 no eligible machine; 124 the job ran past --timeout, or past the end of its machine's allowed_hours plus
the grace period, and was stopped. A job that itself exits with 124 gives the same code; the last stderr line tells
them apart ([lanq] TimedOut: timed out after N min, [lanq] WindowClosed: stopped after N min: ... versus
[lanq] Failed: exit 124).
75 covers two cases, and --json tells them apart with retryable. true: machines are busy, held, asleep or
unreachable, so waiting may help. false: no machine can ever take the job as configured (none has every --needs
capability, --mem is above every machine's total RAM, ...). Then lanq ends at once, without waiting out --wait or
waking anything, and the message starts No eligible machine, and no machine can ever take this job as configured (waiting will not help). To see the choice before a run, use lanq run --dry-run or lanq health --needs a,b.
| Command | What it does |
|---|---|
lanq health [--json] [--wake] |
Probes every machine (one ssh call each, in parallel): load, cores, RAM, disk, memory, free slots, what it is suited for, holds, and what to fix when ssh fails. --wake also wakes machines that look asleep. |
lanq health --needs a,b [--mem GB] [--size C[,C] | --min-size C] [--json] |
Also judges every machine for such a job by the rules lanq run uses: -> eligible (2 slots) or -> not eligible: lacks gpu (...). Exit 0 when at least one machine could take it now, 75 when none could. |
lanq health --on m[,m] [--json] |
Shows only the named machines. |
lanq run --needs a,b [--dir D] [--wait S] [--timeout M] [--mem GB] [--fetch PATTERN ...] [--no-wake] [--json] -- CMD... |
Runs one allowlisted command on the best machine and returns its exit code; --fetch brings files back; --no-wake never wakes a sleeping machine for it. |
lanq run ... --size light,medium -- CMD... or lanq run ... --min-size heavy -- CMD... |
Only machines of that size class (--size: one of the listed classes; --min-size: that class or larger). A machine's size: in machines.yml wins over its probed size; see Routing jobs. |
lanq run ... --on m[,m] -- CMD... |
Only the named machines (an unknown name is refused before any network). Every other rule still applies. |
lanq run ... --env NAME=VALUE ... -- CMD... |
Sets a variable for this job only; the name must be in policy.allowed_env. See Job variables. |
lanq run ... --exclusive -- CMD... |
Takes every slot of the machine, so nothing else runs there meanwhile. See Exclusive jobs. |
lanq run ... --baseline [--baseline-ref REF] -- CMD... |
After a failure, runs the same command at the base commit and says whether the failure is new. See Is this failure new? |
lanq run ... --results trx:PATTERN | junit:PATTERN -- CMD... |
Fetches the job's TRX or JUnit files and counts its tests (since 0.11.0); a completed job that ran no test gets a warning. Never changes the exit code. See Test results. |
lanq run --plan [--plan-file PATH] [--only a,b] [--fail-fast] [--dry-run] [--json] |
Runs the jobs of the repository's lanq.yml side by side on one snapshot, ordered by after:, with one result; see docs/PLANS.md. Since 0.10.0 also --on/--size/--min-size (narrow every job, never widen), --plan-timeout M (the whole plan's limit) and --fetch-dir/--fetch-max/--fetch-max-files (for every fetching job). |
lanq run ... --json --log-tail N -- CMD... |
Adds the last N lines (1 to 200) of the job's log to the JSON object as logTail; logPath is always there. |
lanq run ... --dry-run [--json] -- CMD... |
Says what lanq run would do now (the checks, the snapshot scan, the machine, every excluded machine and why, --shards N and placement) and does none of it. |
lanq run --shards N|auto [--shard-retries R] [--fail-fast] ... -- CMD {shard}/{shards} |
Splits one command into N jobs that run at once across free slots; see Sharding. |
lanq run --shards auto --target-minutes M ... -- CMD {shard}/{shards} |
Picks N from earlier runs of the same command so each shard takes about M minutes (1 to 1440), never more than the free slots; see docs/SHARDING.md. |
lanq stats [--json] [--target-minutes M] |
Summarises your local job log: totals, per machine (median and p90 of completed jobs, speed factor), per command (runs, results, the work and per-shard overhead) and, since 0.10.0, per plan job (per plan file and job name; one run per plan run), and the size of the job logs. --target-minutes M adds the shards M would need. |
lanq doctor [--remote [--force]] [--json] |
Checks your own setup without any network; --remote also checks each worker over ssh. --json prints one object with every check and its fix. |
lanq makeready <machine> or lanq makeready --ssh user@host --os windows|linux [--key-env VAR] [--json] [--force] [--tune] |
Runs the read-only lanq-makeready check on a worker and suggests a machines.yml entry. --key-env VAR scans with the key file whose path is in VAR. --tune adds the read-only tune scan (what slows the PC down as a worker). |
lanq makeready --ssh user@host --os windows|linux --setup [--key-env VAR] |
Prints the PC's full one-time setup (build user, your public key, work folder, firewall, password logins off, the fingerprint check) and connects to nothing. |
lanq makeready --ssh user@host --os windows|linux --add --name NAME [--key-env VAR] [--yes] [--json] |
Scans the PC and, only when it is READY, adds it to your machines.yml (it shows the lines and asks first; --yes without a terminal). |
lanq makeready --all [--json] [--force] [--tune] |
The same check on every configured machine, four at a time, as one summary table (--tune: a TUNE column). |
lanq init [--json] |
Writes a commented starter machines.yml to the per-user config file (or to --config FILE / $LANQ_CONFIG), never into the current folder; never overwrites a file. |
lanq unlock <machine> [--all --yes] |
Removes slot files a crashed lanq left behind. |
lanq wake <machine> [--wait] [--json] |
Sends a Wake-on-LAN magic packet to a machine with a wake: setting, even outside its allowed_hours; --wait waits for ssh. |
lanq --version |
Prints the version (with its commit) and the embedded lanq-makeready scripts: the scanner, and the tune scan (one line each). |
Every command takes --config FILE. An option a command does not use is an error, not silently ignored.
Local by default (no network): ssh (with its version), scp, git and ssh-keygen on PATH; the state folder is
writable; the config loads (the loader's own error otherwise); the job logs in logs/ (count and size, WARN over
2 GB when policy.keep_logs_days is 0); and for each machine a known_hosts entry (host and
port resolved with ssh -G, so ~/.ssh/config counts; a non-22 port is looked up as [host]:port, and a
HostKeyAlias is looked up as it is; the user and global known_hosts files ssh -G names are searched), the key_env
file and whether it has a passphrase. --remote first probes each machine like lanq health: a machine that is
paused (PAUSE file) or outside its allowed_hours gets a HOLD line and nothing else is run there (--force checks
it anyway; HOLD lines do not change the exit code). Then one ssh call per machine, four at a time: is work_root
writable (a temporary file, removed again; a missing work_root is a warning and is not created), is git or tar
there for the machine's transfer mode, and does each capability's tool answer in the job environment, with the
machine's env: and path_prepend: applied exactly as for a job. Each check may take 20 seconds; a check that hangs
is stopped (Linux timeout, Windows a child PowerShell whose tree is killed) and reported as timed out, and the
other checks still run. On a git machine a worker git older than 2.32 is a WARN (see "Hardened git"):
| Capability | Command run |
|---|---|
dotnet / node / npm |
dotnet --version (fails without an SDK) / node --version / npm --version |
python |
python3 --version, falling back to python --version |
go |
go version with GOTOOLCHAIN=local (never downloads a toolchain) |
rust / java |
cargo --version with RUSTUP_AUTO_INSTALL=0 (never installs a toolchain) / java -version |
docker |
docker version --format '{{.Server.Version}}' (the daemon must answer) |
Other capability names are listed as SKIP ... not checked. This is how you find the classic "npm works when I log
in, but npm: not found in a lanq job" problem: a non-login SSH session does not run your shell profile, so add the
tool's folder to path_prepend:. When the dotnet check fails, doctor also searches the worker's install folders
(read-only, a few seconds; docs/WORKERS.md) and, when it finds an
SDK somewhere the job's PATH does not reach (say D:/build/dotnet), the fix names the exact path_prepend: and
DOTNET_ROOT lines to add. On a Windows worker whose build account is denied WMI, a wmi line is a WARN with what
the owner could grant; lanq works without it (docs/WORKERS.md).
Output is one OK, WARN, FAIL or SKIP line per check; the exit code is 0 when nothing is WARN or FAIL,
otherwise 1.
$ lanq doctor --remote
OK ssh: OpenSSH_9.6p1, OpenSSL 3.0.13 30 Jan 2024
OK git: git version 2.47.0
OK config: 2 machine(s)
OK logs: 388 files, 96.2 MB (kept 30 days)
OK build-01: known_hosts has build-01.lan
OK build-01 (remote): dotnet: 10.0.100
FAIL build-01 (remote): npm: 'npm --version' failed in the job environment (sh: 1: npm: not found). If the tool is installed, ...
SKIP build-01 (remote): gpu: not checked (no known tool command)
--json (also with --remote) puts those lines on stderr and prints one object on stdout: status (Ok,
Warnings, Failing, ...), exitCode, counts and one entry per line in checks, each with a name, level and,
where there is one, a fix:
$ lanq doctor --remote --json 2>/dev/null | jq -c '.checks[] | select(.level == "fail")'
{"scope":"remote","machine":"build-01","name":"capability","level":"fail","detail":"npm: 'npm --version' failed in the job environment (...)","fix":"add the tool's folder to path_prepend for this machine","capability":"npm"}The check names and every field are in docs/JSON.md.
Runs lanq-makeready on a worker: a read-only check of SSH, git/tar,
.NET 10, Docker and overnight readiness (sleep, pending reboots, update restarts). The script is built into lanq
(v0.5.0, byte-identical to that release, whose SHA-256 a test pins; only the read-only scanner and the read-only tune
scan: lanq-makeready's fix script is never built in or sent), sent on ssh stdin and run from memory with
-Redact / --redact: nothing is written to the worker's disk, and nothing on it is changed.
lanq makeready build-01for a configured machine. It respects the machine'sPAUSEfile andallowed_hours(exit75);--forcescans anyway. When everyallowed_hoursentry is the same every-dayHH:mm-HH:mmwindow (no days named), lanq passes it to the script as-Hours(0.12.0): the suggested entry then carries thatallowed_hours, and on Windows theupdates.activehourscheck compares Windows Update's active hours with it (it canWARN). Entries that name days (Mon-Fri 18:00-23:00), different windows, or none pass nothing, as before, so the suggestedallowed_hoursis never wider than yours.lanq makeready --ssh user@old-pc.lan --os windowsfor a PC that is not inmachines.ymlyet, once key-based SSH works and its host key is in yourknown_hosts(same key-only, strict-host-key ssh options as every other call; your agent or default key is used).--key-env VARuses the key file whose path is inVARinstead, askey_env:does, and the suggested entry then carrieskey_env: VAR. When the worker refuses the key or its host key is not inknown_hostsyet, lanq also suggests--setup(below).
It prints the verdicts (worker_git, worker_archive, dotnet10, docker, overnight), then the script's own
VERDICT: line (READY, READY WITH WARNINGS (n) or NOT READY (n blockers)) and its numbered next steps, blockers
first, each with the command or settings path to use and whether it needs admin (or root), worded as the script prints
them, and a Suited for: line (light, medium or heavy, "+ container builds" when Docker answers). A report from
lanq-makeready 0.1 has none of these: lanq then lists each WARN/FAIL check with its advice. Then, for a configured
machine, the capabilities detected but not configured and configured but not detected, and a suggested machines.yml
entry: max_jobs and min_free_mem_gb sized from the PC's RAM and CPUs, and, only when the script's Wake-on-LAN check
passed, a commented wake: block to uncomment (the MAC is redacted in the report, so fill in mac:). When a WARN/FAIL check may be one that lanq-makeready's
fix script fixes (Windows: ssh.start, ssh.auto, power.sleep, longpaths.on, git.longpaths, ssh.aclkeys;
Linux: ssh.start, power.sleep), one more line names those fixes: May be fixable at that PC (lanq-makeready-fix:
power.sleep, longpaths.on): its owner can run lanq-makeready-fix.ps1 -WhatIf there to see what it can do, local and
interactive only (see lanq-makeready's README). lanq never runs it. (sh lanq-makeready-fix.sh --dry-run on Linux.)
"May": the fix script has its own preconditions and can still decline. (Since 0.9.1; not in --json.) It ends with: lanq never changes a worker. Fixes are for the PC's
owner to run on that PC. --json prints the validated report (schema lanq-makeready/v1) instead (0.2.0's
summary, suitedFor, min_free_mem_gb and wake included), every string sanitised and suggestedMachine.path_prepend/env
kept only as the one usable folder with DOTNET_ROOT set to it, anything left out named in lanqWithheld (0.9.2; also in --all and --add --json); when there is no report it prints exactly
one {"status":...,"exitCode":...,"message":...} object (Rejected 2, InfraError 70, Held 75, Cancelled 130). The report is
treated as untrusted input: at most 1 MB, parsed without reflection, checked against the schema, every string
sanitised before display, and nothing in it is ever run. Exit codes: 0 worker-ready (git or archive transfer works),
1 not ready, 2 bad arguments, 70 ssh failed or the report was unusable, 75 machine paused or outside its hours,
130 Ctrl+C.
lanq makeready build-01 --tune (0.12.0; also with --ssh ... --os ... and --all) runs, after the check, the
read-only lanq-makeready-tune scan the same way (on ssh stdin, from memory, up to 150 s): what slows the PC down as
a build worker or keeps it busy at night. Windows: the processor power plan, USB selective suspend, PC-maker updaters
(startup entries, services, scheduled tasks), SysMain, Search indexing of the work folder, Delivery Optimization, update
reboots, visual effects, Defender exclusions and scan times, another antivirus, the page file, disk health and fullness,
driver age, plain-text autologon, maintenance times, cache sizes, DOTNET_* machine variables, OneDrive and the work
folder, WSL memory. Linux: the CPU governor, swappiness, inotify limits, the journal size, unused services, unattended
reboots, the package cache, TRIM, SMART, thermal throttling, disk fullness. Each item is OK, INFO, WARN or SKIP,
never FAIL: tuning never changes whether the PC is worker-ready, and the exit code stays the check's. A configured
machine's window goes as -Hours (the times every allowed_hours entry shares, days left out: the tune scan only
compares schedules with them) and its work_root as -WorkRoot (only when the tune script accepts it as written); a
--ssh PC gets neither. Not with --setup or --add.
The text adds a tune section after the report: the counts, each WARN and INFO item with its advice and, when
lanq-makeready's fix script can change it, its fix id (SKIP items only as a count), then Its owner can preview the
tune fixes at that PC: lanq-makeready-fix.ps1 -Tune -WhatIf; local and interactive only. lanq never runs it.
(sudo sh lanq-makeready-fix.sh --tune --dry-run on Linux). --all --tune adds a TUNE column (2 WARN 1 INFO,
timed out, unreachable, unusable, or - for a machine with no report); held and unreachable machines are not
tuned. Each machine takes up to 120 s for the check plus 150 s for the tune scan, four at a time, with no overall limit.
--json adds lanqTune as the report's last key (also in each --all row's report): status (Ok, TimedOut,
Unreachable or Unusable), error (when not Ok), report (the validated lanq-makeready-tune/v1 report) and its
own nextSteps. The tune report is untrusted input like the check's: at most 256 KB and 64 items, parsed without
reflection, checked (schema, ids, statuses, summary counts), every string sanitised and cut to length. fixId is kept
only when it is the one lanq's own table expects for that item, and security only for the items lanq knows are
security relevant. advice and detail are text for the PC's owner: nothing in them is ever run, and lanq never sends
or runs the fix script. The fields are in docs/JSON.md.
lanq makeready --all runs the same check on every machine in the config, four at a time, with the same rules (a
paused machine or one outside its allowed_hours is not scanned unless --force; the script goes on ssh stdin), and
prints one table:
$ lanq makeready --all
lanq makeready --all: 4 machine(s), read-only (lanq-makeready 0.5.0)
MACHINE OS VERDICT TOP PROBLEM
micro-01 linux WARN 1 Pending reboot: a restart is pending
micro-02 windows FAIL 1 OpenSSH Server: not installed
family-pc windows held paused (a PAUSE file is in its work_root); --force scans anyway
micro-03 linux unreachable ssh: connect to host 10.20.30.33 port 22: Connection timed out
Details, advice and a suggested machines.yml entry for one machine: lanq makeready <machine>
lanq never changes a worker. Fixes are for the PC's owner to run on that PC.
The verdict is FAIL n only when the machine is NOT READY (no transfer mode works, so lanq makeready <machine> exits
1), with n blockers; else WARN n with n things to look at, else OK. A FAIL check that does not stop the PC being
a worker (Docker, .NET) is one of the warnings, as in the script's own verdict. The counts and the top problem come from
the report's summary (lanq-makeready 0.2.0: its first next step, blockers first); for a 0.1 report, from its checks (the
first failing check, else the first warning). unreachable (the probe or ssh failed), held or error (the report was
unusable) when there is no report, with why as the top problem. Exit codes, first match wins: 70 any machine was
unreachable or its report unusable (the check is incomplete); 1 any machine is NOT READY; 75 any was held; 0
otherwise. Warnings alone exit 0, as lanq makeready <machine> does; they stay in the table and the JSON. 2 means bad arguments or config, 130 Ctrl+C. With --json it prints exactly
one object, {"status":"Ok|Failing|InfraError|Held","exitCode":...,"machines":[...]}, where each machine has machine,
os, verdict (OK, WARN, FAIL, unreachable, held or error), warnings, failures (blockers), exitCode (what
lanq makeready <machine> would exit with), problem (absent when there is none) and report: the validated
lanq-makeready/v1 report exactly as lanq makeready <machine> --json prints it (absent without one). A bad argument
or config prints the usual {"status":"Rejected","exitCode":2,"message":...} object instead.
Two steps add a new PC. Both write only on your computer; lanq still never changes a worker.
lanq makeready --ssh build@10.20.30.21 --os windows --setup (or --os linux) prints the PC's full one-time setup and
connects to nothing: the build user (the build of build@..., not an administrator; root and administrator are
refused), your public key in its authorized_keys (Windows: icacls with every grant by SID and inheritance cut;
Linux: .ssh 700 and authorized_keys 600), the work folder (C:/lq or /srv/lq, the work_root lanq makeready
suggests), firewall scoping, the command that shows the host key fingerprint, the first connection from your computer
(compare the fingerprint before answering yes), and password logins off once the key works. The PC's owner runs the
worker part. The key is the first one ssh-add -L lists, else ~/.ssh/lanq_ed25519.pub, else ~/.ssh/id_ed25519.pub;
with --key-env VAR, only the .pub beside the key VAR names. lanq reads only .pub files and checks each key
line; without a usable key the commands hold a placeholder and the output says how to make one. Text only (--json is
refused), exit 0. docs/TEAM-QUICKSTART.md explains every step.
lanq makeready --ssh build@10.20.30.21 --os windows --add --name micro-01 then scans the PC as lanq makeready --ssh
does and, only when it is READY (with or without warnings), adds its entry to your machines.yml (found as for every
command, or --config FILE):
- Before the scan it checks the arguments, that the config loads, that no machine has that name (ignoring case) or
that host, and that it can edit the file by itself: one YAML document, one block-style top-level
machines:, no tabs, not a link. Otherwise it refuses (exit2) and you paste the entry by hand. - The entry goes in as text after the last machine (before
lanq init's commented examples), lined up with the file's own items. Every other byte, CRLF or LF and a BOM are kept. The lines it shows are the lines it writes. - It checks the result before writing (it loads, holds exactly one machine more, the others are unchanged), then replaces the file atomically (keeping its Unix mode, or its ACL on Windows), never through a link and never over a file that changed meanwhile.
- It asks first on a terminal. Without one, and always with
--json, it needs--yes. - Then one read-only probe of the new machine (never a wake), printed as a
lanq healthline, a warning whenlanq init'sexample-01is still there, andNext: lanq doctor --remote.
Exit 0 added; 1 NOT READY or declined (nothing written); 2 bad arguments, config, a duplicate or a file it does not
edit; 70 ssh failed, the report was unusable or the file could not be written. --json prints one object (see
docs/JSON.md).
lanq init writes a commented, minimal machines.yml to the per-user config file that lanq reads without flags
(%APPDATA%\lanq\machines.yml on Windows, ~/.config/lanq/machines.yml elsewhere; $XDG_CONFIG_HOME is honoured),
or to --config FILE or $LANQ_CONFIG when given, creating the folder. It never writes into the current folder (which
may be a repository; since 0.8.0, earlier versions wrote ./machines.yml). Text and JSON say the path written.
It never overwrites a file and never writes through a link: an existing file, folder or link (even one
pointing nowhere) at that path is refused (exit 2). The file loads as written: a policy memory floor suited to
small PCs (min_free_mem_gb: 1.5), one live example machine to replace (max_jobs: 1, set per machine), and commented examples of a
Windows micro PC (key_env, a memory floor, heap caps) and a Linux family PC (allowed_hours, wake:). It then
prints the next steps: lanq makeready --ssh user@host --os windows|linux --setup for each worker's one-time setup
(see Adding a machine), lanq makeready --ssh user@host --os windows|linux --add --name NAME to add each one once it is ready, delete example-01, then lanq doctor --remote. Remember that lanq
never reads ./machines.yml by itself: the steps include --config with the file's path unless you wrote it to the
per-user path. --json prints one object ({"status":"Created","exitCode":0,"path":...,"message":...,"nextSteps":[...]};
Rejected 2 when the file exists, InfraError 70 when it could not be written) and sends the next steps to stderr.
A slot file records its deadline; lanq run reclaims a slot 30 minutes after it. lanq unlock build-01 removes
the slots that are already past their deadline right away and says what it removed and what it kept (a live slot,
or one written by a lanq before 0.4, which has no deadline). lanq unlock build-01 --all --yes removes every slot
file on that machine, including those old ones; a job still running there keeps running but loses its slot, so
another job may start beside it. --all without --yes is refused.
lanq run --needs dotnet --dir tests --fetch 'TestResults/**/*.trx' --fetch '**/coverage.cobertura.xml' -- dotnet test --logger trxAfter the job ends, whether it passed, failed, timed out or was stopped by its machine's hours, and before the job
folder is deleted, lanq copies the files that match back to .lanq/artifacts/<job id>/ in your repository (the
.lanq folder is never sent to a worker and gets a .gitignore), keeping their relative paths. Nothing is fetched
when the job never started.
- A pattern is relative to the job's working folder (
--dir), uses forward slashes, and only*(within one name),?(one character) and**(a whole segment: any number of folders). Absolute paths, drive letters,.., backslashes,:and a leading-are refused, as is any character outside letters, digits, space and. _ + @ = , ~ - /.--fetchmay be given up to 16 times. On a Windows worker patterns match ignoring case. - Only regular files are fetched. Symlinks, junctions and other reparse points (never followed, not even as folders), hard-linked files (Linux), devices, FIFOs, names with control characters and anything that resolves outside the job folder are skipped and listed with the reason.
- Caps: 500 files and 200 MB in all by default;
--fetch-max-files N(up to 5000) and--fetch-max SIZE(for example500Mor1G, up to2G) change them. Files are taken in sorted order until a cap is hit; the rest are listed as skipped. --fetch-dir DIRwrites toDIR/<job id>/instead. Keep it gitignored or under.lanq/: fetched files (a TRX file carries the worker's user and host) would otherwise be sent with the next snapshot.- The fetch has its own 10-minute limit, and on a machine with
allowed_hoursit never runs more than 2 minutes past the end of the window plus grace. - A job that timed out or was stopped by its window can still be running on the worker (which enforces the limit
itself a minute later), so before fetching
lanqstops it the way cleanup does: the recorded process group on Linux, and on Windows only the recorded processes whose pid and start time still match. A job that completed or failed is not touched. - A job whose ssh connection dropped while it ran (
InfraError) may also still be running there:lanqstops it the same way on a fresh connection and fetches what it left (cleanup would kill it next anyway). If the machine does not answer that either, nothing is fetched andfetchErroris "not fetched: the SSH connection failed during the job". ssh reports a lost connection as exit 255, which a job can also exit with; the job wrapper therefore ends its output with aLANQ_EXIT=<job id>:<code>line (taken off the output), and a 255 counts as the job's own exit only when that line is the final one and says 255; otherwise it is a lost connection. The line decides nothing else: any other exit code is ssh's, and a marker-shaped line that is not the last one is shown as ordinary output. A job that exits 255 itself isFailedwith exit 255. - Each file is written as a short
.lanq-partial-Nfile in the same folder and renamed to its name only once its size and hash are right. Anything the worker prints on stderr during the fetch is shown as[lanq] fetch stderr: ...(the first 10 lines, sanitised) and never mixed into the files. - Fetch problems never change the exit code: the job's result is what
lanqreports, and a skipped or failed file is listed in the summary (and in--json). A job that passed but whose results did not come back is still a passed job; checkfetchErrorandfetchSkippedwhen the files matter.
The summary goes to the job output (stderr with --json):
[lanq] fetch (the job failed (exit 1)): 2 file(s), 1.4 MB -> /home/me/src/app/.lanq/artifacts/20261109-221503-a1b2c3
[lanq] fetched TestResults/unit.trx (1.3 MB)
[lanq] fetched TestResults/coverage.cobertura.xml (96.2 KB)
[lanq] skipped TestResults/latest.trx: symbolic link, junction or reparse point (never followed)
The worker is treated as untrusted for this step; see Security model.
lanq run --needs dotnet --dir tests --results trx:TestResults/*.trx -- dotnet test --logger trx
lanq run --needs node --results junit:reports/junit.xml -- npx jest --reporters=default --reporters=jest-junitSince 0.11.0 --results trx:PATTERN or junit:PATTERN (in lanq.yml: results: { format: trx, path: ... }) names
the results files the job writes. The pattern is a --fetch pattern and is fetched too (it counts as --fetch,
unless a --fetch already names it), so the fetch rules, limits and fields all apply. After the fetch, lanq counts
the tests in the fetched files that match: VSTest TRX (xUnit, NUnit, MSTest) or JUnit XML (pytest, jest-junit,
Maven Surefire and most others). The job output gets the reader's warnings, [lanq] results: 120 tests, 118 passed, 1 failed, 1 skipped and up to 10 [lanq] failed NAME lines; --json gets a results object.
When a job completed but its results show no test executed (no file matched, or every test was skipped), lanq
prints [lanq] warning: no tests ran: 0 executed in 0 results file(s) (results path TestResults/*.trx) before the Next
lines and adds an ask_developer step: a wrong filter or test project would otherwise pass silently. When the results
could not be read (a file over a cap or not valid XML, a fetch error, a results file the fetch skipped), noTestsReason
is results_unreadable and lanq says results could not be read instead: whether tests ran is unknown. It is
information only: the status and exit code never change (a sharded job is judged after its shards are merged; a
single empty shard never warns). Making it fail is planned as an opt-in (see
docs/PLANS.md). Test names are data the worker wrote, sanitised: never run them.
Scripts and coding agents should prefer --json; docs/JSON.md is the full contract.
lanq health --json prints one array, in config order:
[{"name":"build-01","state":"ok","reasons":[],"load":0.12,"diskFreeGb":180.4,"memFreeGb":9.8,"slotsUsed":0,"maxJobs":2,"localTime":"2026-11-09T22:15:03","cores":8,"memTotalGb":15.6,"loadKnown":true,"freeSlots":2,"size":"heavy","sizeSource":"probe","suitedFor":"heavy: full suites and large builds","nextSteps":[{"action":"none","reason":"build-01 can take work","safeToRunUnattended":false}]},
{"name":"build-02","state":"hold","reasons":["outside allowed hours"],"load":0.05,"diskFreeGb":90.1,"memFreeGb":null,"slotsUsed":0,"maxJobs":1,"localTime":null,"cores":4,"memTotalGb":null,"loadKnown":true,"freeSlots":1,"size":"unknown","sizeSource":"probe","suitedFor":"unknown: the machine did not report its memory","nextSteps":[{"action":"wait","reason":"build-02 is outside allowed hours; it takes jobs again in its next window (allowed hours: Mon-Fri 22:00-07:00)","safeToRunUnattended":false}]}]state is ok, hold or down; reasons is empty when ok; memFreeGb and localTime (the worker's own clock)
are null when the worker does not report them; so are cores and memTotalGb (then size is unknown).
freeSlots is maxJobs minus the live slots in use (0 for a machine that is down); since 0.9.0 slotsStale (only when above 0) counts the slots in slotsUsed that a crashed run left more than 30 minutes past their deadline, which the next claim reclaims, and size is light, medium, heavy
or unknown: the machine's size: in machines.yml when it has one (sizeSource config), else the probed class
(sizeSource probe). loadKnown is false only when a Windows worker could not measure its load at all (then
load means nothing). With --needs a,b, --mem GB, --size and/or --min-size, each row also has eligible, why and reason (null when
eligible), permanent (waiting can never change it) and jobSlots (how many copies or shards of such a job it could
take now, --mem counted per copy); without them the rows are exactly as above.
lanq run --json streams the job's output to stderr and prints one object on stdout when it is over:
{"status":"Completed","exitCode":0,"machine":"build-02","jobId":"20261109-221503-a1b2c3","durationSeconds":84.2,"message":"exit 0","logPath":"/home/me/.local/state/lanq/logs/20261109-221503-a1b2c3.log","nextSteps":[{"action":"none","reason":"the job completed","safeToRunUnattended":false}]}logPath is always there: the full path of the job's local log (every line lanq printed for the job), null when no
job started. --log-tail N (1 to 200, --json only) adds logTail, the log's last N lines (sanitised, empty when no
job started), so a script or agent needs no stderr redirect to see why a job failed. In text mode lanq prints
[lanq] log: <path> on stderr just before the status line. On NoCapacity the object adds retryable (false when no
machine can ever take the job, so waiting will not help) and excluded, one {machine, reason, why, permanent} per
machine; reason is a code such as missing_capability or busy (the table).
With --fetch the object also has fetched ([{"path":"TestResults/unit.trx","bytes":1363148,"sha256":"..."}]) and
fetchSkipped ([{"path":"TestResults/latest.trx","reason":"..."}]), both present and possibly empty on every path
(also when the job never started, the command line was refused or the config could not be read), plus fetchDir when a fetch ran, fetchError when the fetch as a whole had a
problem (timed out, cut short, the machine's hours ended, the ssh connection was lost) and fetchSkippedMore when more than 200 files were skipped.
Without --fetch none of these keys appear. --results counts as --fetch; since 0.11.0 it also adds results (the
counts, noTests, at most 50 failedTests and warnings) whenever the job ran, as the last key
(docs/JSON.md).
Since 0.9.0, with --env the object has env (the variable names, never their values); with --exclusive,
"exclusive":true; and with --baseline, after a failure, a baseline object (ref, sha, status, exitCode,
machine, jobId, logPath, durationSeconds, verdict, message). Each is left out when it does not apply
(docs/JSON.md).
status is Completed, Failed, Rejected, NoCapacity, InfraError, TimedOut, WindowClosed or Cancelled;
exitCode is lanq's own exit code; machine is null when no machine took the job. Stdout always carries exactly
one such object, also when the job never started: bad arguments or a config error (Rejected, 2, jobId null),
Ctrl+C (Cancelled, 130) or an unexpected error (InfraError, 70). lanq health --json with a bad argument or
config prints {"status":"Rejected","exitCode":2,"message":...,"nextSteps":[...]} instead of its array, and Cancelled
(130) or InfraError (70) objects of the same shape when interrupted or broken. The [lanq] ... status line
and error messages still go to stderr, and so does the usage text after an unknown command (lanq --help prints it
on stdout). lanq run --dry-run --json prints one object with status WouldRun (exit 0) or the status the run
would end with, the machine, every machine as judged for the job and, with --shards, N and the placement.
lanq run --plan --json prints one object for the whole plan with a jobs array (one entry per job, by name), and
lanq run --plan --dry-run --json one with each job's lanq run line and what it would do
(docs/JSON.md); with a plan limit both add planTimeoutMinutes, and a plan
that reached it adds planTimedOut: true.
lanq doctor --json prints one object with every check (see lanq doctor), and lanq stats --json one
object with the totals, machines, commands (each with its timing), planJobs and logs.
nextSteps. Every --json object (each lanq health row, the run, dry-run, init, wake, doctor, stats,
makeready --all and --add objects and every error object) carries nextSteps, at least one entry:
{"action","reason","command"?,"argv"?,"safeToRunUnattended"}. action is proceed, retry, wait, fix_code,
fix_command, ask_developer, run_doctor, run_health or none; treat one you do not know as ask_developer.
argv is the exact command and is authoritative; command is the same as one line for bash and PowerShell, left out
when an argument cannot be written safely for both. A suggestion never does more than the command that produced it,
and only safeToRunUnattended: true steps are for a script or agent to run by itself. The one exception is the single
lanq makeready <machine> --json report, which stays the lanq-makeready script's own report with no top-level
nextSteps (its error objects have them; with --tune, the tune steps are inside lanqTune). For people, the same steps are printed as Next: ... lines on stderr ([lanq] Next: ...
inside lanq run), before the status line, which stays last. The full contract is in
docs/JSON.md.
sequenceDiagram
autonumber
participant Dev as You or your agent
participant L as lanq (local)
participant M as Chosen machine
Dev->>L: lanq run --needs dotnet -- dotnet test
L->>L: Policy: command and directory allowlists
L->>L: Snapshot HEAD + overlay (throwaway index), secret scan
L->>M: Health probe of every machine (ssh)
L->>L: Skip held machines, pick least loaded with the needed capabilities
L->>M: Claim a slot file (max_jobs)
L->>M: scp the git bundle
L->>M: Fetch into a bare cache, add a per-job worktree
L->>M: Run the allowlisted command in the worktree
M-->>L: Stream the log (terminal and state folder)
L->>M: Kill the process group, remove worktree, ref, bundle and slot
L->>L: Record the job in jobs.jsonl
L-->>Dev: Exit code = the job's exit code
Where each safety check sits (numbers are the diagram steps):
| Step | Check |
|---|---|
| 2 | Command and directory must match your allowlists; permission-skipping flags are refused. Nothing has touched the network yet. |
| 3 | The command line and the uncommitted overlay are secret-scanned, and committed file names are checked; a hit refuses the job before anything is sent. |
| 4-5 | Machines that are unreachable, paused, loaded, outside their hours (or about to close), low on disk or memory, under memory pressure or missing a capability are skipped. |
| 6 | max_jobs is enforced with an atomic slot file per machine; a slot left by a crashed run counts as stale 30 minutes after its recorded deadline: it no longer makes the machine busy, and the next claim reclaims it. |
| 4-10 | Every ssh/scp call is key-only, non-interactive and uses StrictHostKeyChecking=yes. |
| 11 | Cleanup runs even when the job fails, is cancelled or times out (best effort if the network is down). |
- The command and directory are checked against your policy. Rejected jobs never touch the network.
- HEAD plus uncommitted and untracked, non-ignored files are snapshotted into a commit using a temporary index (your index, branches and working tree are untouched) and bundled. The overlay is scanned for secrets.
- Every machine is probed; those that are unreachable, over the load threshold, outside their hours, full or missing a required capability are skipped. The rest are ranked by load.
- A slot file is claimed atomically on the chosen machine (
max_jobsper machine), the bundle is uploaded withscp, fetched into a bare cache repo, and a detachedgit worktreeis created for the job. - The command runs in the worktree; output streams to your terminal and to
<state>/logs/<job>.log, where<state>is$LANQ_HOMEor a per-user folder (%LOCALAPPDATA%\lanq, or~/.local/state/lanq), never your repo. - With
--fetch, the matching files are streamed back as checksummed text and written below.lanq/artifacts/<job id>/. - The worktree, ref, bundle and slot are removed, even if the job failed. One line about the job is appended to
<state>/jobs.jsonl. Any.lanq/folder in the repository is excluded from the snapshot.
lanq keeps its state on your computer, in <state> ($LANQ_HOME, else %LOCALAPPDATA%\lanq on Windows, else
$XDG_STATE_HOME/lanq or ~/.local/state/lanq). Nothing in it leaves this machine.
jobs.jsonl: one JSON line per finished job:id,machine,command,startedUtc,wallSeconds,exitCodeandstatus, and since 0.7.0v(2),key(the command; for--shardsits arguments with{shard}and{shards}),dir,shard,shardsandrunId(shared by the shards of one run), andrunSeconds(how long the command itself ran, without the wait, upload, prepare, fetch or cleanup), and since 0.8.0planJobandplanRunfor the jobs of alanq run --plan(the job's name inlanq.yml, and an id shared by one plan run), and since 0.9.0envNames(the names of the job's--envvariables, never their values),exclusiveand, on a--baselinererun,baselineOf(the failed job's id) andcommit(the base commit's short id), and since 0.10.0planFileon a plan job (the plan file's full path;lanq statsgroups plan jobs by it, so clones in different folders count separately). A field that does not apply is left out. Baseline reruns ran another commit, solanq stats,--target-minutesand a plan's order leave them out. At 4 MiB the file moves tojobs.1.jsonl(replacing the one before), so there are at most two files; lanq reads both, and lanq 0.6 reads onlyjobs.jsonl.jobs.jsonl.lockmakes two lanq processes take turns writing. A job that cannot be recorded (the file is locked for long) gets a warning; its result does not change. A line lanq cannot read is skipped and counted bylanq stats.logs/<job id>.log: every line lanq printed for a job. After a run, at most once a day, lanq deletes its own logs older thanpolicy.keep_logs_days(default 30; 0 never deletes) and the oldest beyond 5,000. It never deletes a log modified in the last hour, a link or any other file, and a prune that takes over 2 seconds stops and carries on after the next run.lanq doctorandlanq statsshow the count and size.bases.json(which git bases each worker has) andtmp/(scratch for bundles and archives).
lanq stats, --target-minutes and the speed factors read only these files. Do not edit or delete jobs.jsonl or
logs/ while lanq runs; to start over, delete jobs.jsonl and jobs.1.jsonl when no lanq is running.
Each machine in machines.yml has an optional transfer setting:
git(the default, recommended):lanqsends a git bundle and the worker keeps one bare cache repo per repository (<work_root>/repos/<repoid>.git, named after the first 16 hex digits of the root commit) with a detached worktree per job. Later jobs on the same worker are cheaper to prepare. The worker needsgit. (Versions before 0.4 used a single shared<work_root>/repo.git; it is no longer used and can be deleted.)archive:lanqbuilds the same snapshot (HEAD plus uncommitted and untracked files, honouring.gitignore, never.lanq/) on your PC and sends it as atar.gz; the worker extracts it into a fresh per-job folder with its owntar: GNU tar (with gzip) on Linux, or the bsdtar built into Windows 10 1803+ / Server 2019+. The worker does not need git at all, so the old PC that cannot or should not have git installed still joins the queue: SSH + tar + your toolchain. A worker whosetaris busybox tar (Alpine and many minimal images) is refused, because its listing cannot be trusted; install GNU tar there or usetransfer: git.
Everything else is identical in both modes: the allowlists, forbidden flags and secret scan run on your PC before
anything is sent, the directory checks and process-group kill apply to the job folder, and cleanup removes the job
folder, the upload and the slot. Archive mode copies the files, not history, so a job that needs git metadata (for
example one that runs git log or git describe) should run on a git machine. Symlinks and submodules are
skipped, not archived (only regular files and directories are), and the job output reports how many were skipped.
Paths that Windows cannot store (names ending in a dot or space, the characters <>:"|?*, or device names such as
CON, NUL or COM1) make the archive build fail with the offending path and rule, because any worker could be a
Windows one.
The first job for a repository on a machine sends a full bundle. After a worker has fetched a snapshot, lanq
records the commit it was taken on in <state>/bases.json (per machine and repository; written atomically), and the
worker's cache keeps refs/lanq/base on that snapshot so the objects stay put. The next job bundles only what is new
(git bundle create … --not <base>), as long as the base is still a local ancestor of the new snapshot. The worker
runs git bundle verify before fetching; if its cache no longer has the base (for example it was deleted), the job
falls back once to a full bundle automatically and the log says so. Rewritten history (rebase, amend, reset) or a
missing bases.json simply mean a full bundle; deleting bases.json is always safe. A --baseline rerun of an older
commit leaves the worker's newer base (and bases.json) as it was, so the next normal job stays incremental.
lanq health checks git --version on git machines, and on archive machines that tar is GNU tar or bsdtar
(plus gzip on Linux), and holds a machine that lacks the tool, with the reason.
An old PC is often still someone's PC: a family desktop, a partner's laptop, the kids' homework machine. Four
settings keep lanq a polite guest there (a full example is the "family PC" entry in machines.example.yml):
-
Hours by day.
allowed_hourstakes one window or a list, each[Days ]HH:mm-HH:mm:allowed_hours: - "Mon-Fri 22:00-07:00" # weeknights; a window that crosses midnight belongs to the day it starts - "Sat,Sun 01:00-09:00" # Mon..Sun, ranges with '-', lists with ','
Times are the worker's own clock (the probe reports it); a worker that does not report one is checked against your PC's clock and
lanq healthshowstime: local. A machine whose window ends withinpolicy.min_window_minutes(default 10) takes no new job ("window closing"). A job still running when the window ends getspolicy.window_grace_minutes(default 15) more, then it is stopped and cleaned up like a timeout: exit124, status[lanq] WindowClosed. -
A PAUSE switch anyone can use. If a file named
PAUSEexists in the machine'swork_root,lanqholds the machine ("paused on the machine") and starts nothing there. No lanq knowledge needed:- Windows: in a Command Prompt,
type nul > C:\lq\PAUSE(use yourwork_root), anddel C:\lq\PAUSEto resume. Friendlier: put two desktop shortcuts on that PC, "Pause builds" with the targetcmd /c type nul > C:\lq\PAUSEand "Resume builds" with the targetcmd /c del C:\lq\PAUSE. - Linux:
touch /srv/lq/PAUSEto pause,rm /srv/lq/PAUSEto resume.
The person needs write access to the
work_rootfolder (grant it once, or make the shortcuts for an account that has it). Only the file's existence counts; its content is ignored. On Linux the name isPAUSEorpause(those two spellings only, since Linux file names are case-sensitive); on Windows any case works.A job that is already running is not affected: PAUSE only stops new jobs from starting there. To end a running job now, stop
lanq runon your PC (Ctrl+C), which cleans the job up on the worker. - Windows: in a Command Prompt,
-
Low priority (the default).
priority: lowruns the job withnice -n 10andionice -c3on Linux (when they exist and work) and at BelowNormal priority on Windows (inherited by every process the job starts), so the person at the keyboard keeps a responsive machine. Setpriority: normalon a dedicated build box. -
Memory. See the next section.
-
Wake-on-LAN for a PC that sleeps outside its hours. See below.
A family PC that is asleep or off outside its allowed_hours can be woken by lanq when its window opens. Opt in per
machine:
wake:
mac: "aa:bb:cc:dd:ee:ff" # required; aa:bb:cc:dd:ee:ff or aa-bb-cc-dd-ee-ff
broadcast: 10.20.30.255 # optional IPv4 literal; default 255.255.255.255
port: 9 # optional, 7 or 9 (default 9)
wait_seconds: 120 # optional, 1 to 600 (default 120): how long to wait for ssh after the packetbroadcast must be 255.255.255.255 or a private (10.x, 172.16-31.x, 192.168.x) or link-local (169.254.x) IPv4
address; a public, multicast, loopback or 0.0.0.0 address is refused when the config loads (this is a LAN tool).
On a computer with several network cards, a VPN or WSL, the default 255.255.255.255 may leave through the wrong
interface: set broadcast to the directed broadcast of the worker's own subnet (for 10.20.30.0/24, that is
10.20.30.255).
lanq runwakes a machine only as a last resort. If no awake machine can take the job now, and you gave a real--wait(above 0),lanqwakes one machine: the first by name among those that look asleep, have awake:setting, have the capabilities the job needs, could take its arguments (a Windows machine is skipped for arguments Windows cannot take) and are inside theirallowed_hourswith at leastpolicy.min_window_minutesplus the machine'swake.wait_secondsof the window left (10 min + 120 s by default): a machine with less left would be held as "window closing" once awake, so it is left asleep and the reason is shown. Nothing is woken while an awake machine can take the job, with--wait 0(the default), or with--no-wake. The wake happens inside--wait: it never makeslanq runwait longer than you asked, and the other machines keep being tried meanwhile. At most once per machine perlanqinvocation, and not another machine while one is still coming up. When every awake machine that fits the job is merely busy,lanqmay therefore wake a sleeper for extra capacity; use--no-waketo avoid that. If a woken machine never answers, the next eligible sleeper (by name) may be tried once the first one'swait_secondshave passed, still within--waitand with at most one packet per machine per run.lanq healthstays read-only and quick. It never wakes anything by itself.lanq health --wakesends a packet to every machine that looks asleep and is inside its hours with that much of its window left, then waits for each (probing again after 5 s, 10 s, then every 20 s, up towait_seconds).- What counts as asleep: ssh itself said, on its own
ssh: connect to host ...line, that the connection timed out or the host or network is unreachable (the Windows OpenSSH wordings are recognised too). A refused connection (the PC is up, sshd is not), an authentication failure or a host-key failure never wake a machine. A localized (non-English) ssh message is not recognised, which fails safe: the automatic wake does not fire, andlanq wakestill works. - Hours and the PAUSE file. A sleeping PC cannot report its own clock or a
PAUSEfile, so the hours check before a wake uses this computer's clock and time zone; on a daylight-saving night it may be an hour off. A paused machine that is awake is reported as paused and never woken, but a PC that is already asleep may well be paused: it will be woken, then held as "paused on the machine" once it answers. - Explicit:
lanq wake build-02sends the packet whatever the hour, because you asked for that machine by name, and says so.--waitthen waits for ssh and exits 0 when it answers, 1 when it does not withinwait_seconds. With--jsonit prints one object,{"status":"Sent|Awake|NoAnswer","exitCode":0,"machine":...,"sent":true,"awake":null|bool,"durationSeconds":...,"message":...}, or the usual{"status":"Rejected|InfraError|Cancelled","exitCode":...,"message":...}when nothing was sent. lanq doctorreports the wake setting. It cannot tell whether the machine will actually wake: Wake-on-LAN has to be enabled in the BIOS/UEFI and the network card driver, and usually only works on wired Ethernet. See docs/WORKERS.md. The packet is unauthenticated and only meant for your LAN (see SECURITY.md).
lanq health reports each machine's available memory (Linux MemAvailable and free swap, plus memory pressure
from /proc/pressure/memory where the kernel has it; Windows free physical memory). A machine is held when:
- it has less than
policy.min_free_mem_gbavailable (default 1.0; a machine can set its ownmin_free_mem_gb): "low memory (0.8 GB free)"; - on Linux, the PSI
some avg10figure (the share of the last 10 seconds in which tasks stalled waiting for memory) is abovepolicy.max_mem_pressure(default 20): "memory pressure".
A machine that does not report memory (an older kernel, an unusual host) is not held for it. A job that needs a lot
of memory can ask: lanq run --mem 6 ... goes only to a machine that reports at least 6 GB available, and never to
one that cannot report it.
How many jobs a machine should take at once follows its RAM and CPUs: max_jobs 1 under 6 GB, 2 under 12 GB, 3
under 24 GB (4 with 8+ CPUs), else 6 (8 with 16+ CPUs), never above the CPU count, and min_free_mem_gb 1.5 under
6 GB, else 2. lanq makeready suggests exactly that; the table and the reasons are in
docs/SHARDING.md, Sizing machines, and the other small-PC settings in
docs/TEAM-QUICKSTART.md.
Build tools size themselves to the machine, which on a 4 GB box usually means swapping. Cap them per machine with
env: (set for the job only):
env:
DOTNET_GCHeapHardLimitPercent: "0x32" # .NET: GC heap at most 50% of RAM (the value is hexadecimal)
NODE_OPTIONS: "--max-old-space-size=2048" # Node: 2 GB heap
CARGO_BUILD_JOBS: "2" # Rust: two parallel compile jobsFor .NET builds the parallelism is a command-line switch, not an environment variable: dotnet build and
dotnet test build several projects at once by default (MSBuild's -maxcpucount, -m); on a small machine run
them as dotnet build -m:1 and dotnet test -m:1 (one build process). The allowlist entries dotnet build and dotnet test
already allow the extra argument.
Tools installed per user (nvm, pyenv, rustup, sdkman) are often missing in a non-login SSH session, because they put
themselves on PATH from .bashrc or .profile. List their folders under path_prepend: and the job finds them:
path_prepend:
- /home/build/.nvm/versions/node/v22.11.0/bin
- /home/build/.cargo/binThe same goes for a toolchain in a private folder, for example a .NET SDK in D:/build/dotnet on a Windows worker
whose PATH only has a runtime-only dotnet: path_prepend: [D:/build/dotnet] plus DOTNET_ROOT: D:/build/dotnet
under env:. lanq doctor --remote finds such a folder and prints these lines; lanq never edits machines.yml itself.
env: names must be letters, digits and _; values may not be empty (Windows PowerShell 5.1 cannot set an empty
variable, so an empty value is refused everywhere: leave the variable out) or contain control characters. As a
best-effort guard against mistakes (the config's author is trusted), names that can hijack the program loader or a
shell are refused (LD_*, DYLD_*, GLIBC_TUNABLES, BASH_ENV, ENV, SHELLOPTS, BASHOPTS, PS4,
PROMPT_COMMAND, PSModulePath, COMSPEC, PATHEXT), and PATH is set only through path_prepend (absolute
directories; a drive path such as C:/Users/build/.cargo/bin on Windows). Values reach the job as data: on Linux each
NAME=value is one single-quoted word passed to env, on Windows a single-quoted PowerShell string, so quotes,
$( ) or backticks in a value are never run.
env: here is per machine and set by you. For a setting one job needs (a configuration, a test filter), use
--env instead. A machine whose env: sets the same name is not used for that job.
A long test suite can run as N pieces at once, one per free slot, while your dev PC keeps working:
lanq run --needs node --shards 4 -- npx jest --shard={shard}/{shards}
lanq run --needs node --shards auto -- npx playwright test --shard={shard}/{shards}
lanq run --needs rust --shards 4 -- cargo nextest run --partition slice:{shard}/{shards}--shards N(1 to 64) starts N jobs of one command, each with its own job id;--shards autouses the number of free slots on the machines that can take the job now (and says why). A machine withmax_jobs: 4takes up to four shards at once, amax_jobs: 1micro PC one.{shard}(1-based) and{shards}are replaced by numbers in the arguments only, and each job also getsLANQ_SHARDandLANQ_SHARDS. Every shard's command line passes the allowlist, the permission-flag ban and the secret scan before anything is sent.- The repository is snapshotted once and each bundle or archive built once for all shards. Shards beyond the free
slots wait for a sibling to finish;
--waitcounts only while no shard of the run holds a slot.--memis per shard: a machine takes at most as many shards as its free memory covers. - Output lines are prefixed
[i/N machine], and a summary table ends the run. Exit 0 only if every shard passed; otherwise the failing shard's own code, else 2, 124, 70 or 75.--jsonprints one object with ashardsarray. --fail-fastcancels the rest after the first shard that fails;--shard-retries R(0 to 3) re-runs only a shard whose machine stopped answering, never a test failure. Ctrl+C cancels every shard and cleans each one up.--dry-runwith--shards autoshows the N it would pick and where each shard would start, and runs nothing.--shards auto --target-minutes Mpicks N from earlier completed runs of the same command, so each shard takes about M minutes on the slowest machine it would go to, never more than the free slots. Without history it is plain--shards auto. See Choosing N from history; lanq picks N, and the test runner decides which tests go in each shard (recipes).
lanq health also shows each machine's cores, total RAM, free/total slots and what it is suited for (light under
6 GB, medium 6 to under 16 GB, heavy 16 GB or more with 4+ cores, "+ container builds" with a docker capability);
health --json adds cores, memTotalGb, freeSlots, size and suitedFor.
docs/SHARDING.md has per-ecosystem recipes (.NET, Node, Python, Go, Rust), a sizing table for
max_jobs and min_free_mem_gb, and a worked plan for 2 dev boxes and 4 micro PCs; setting up the pool itself is in
docs/TEAM-QUICKSTART.md.
Parallel worktrees. Several developers or AI agents can work on one PC at once, each in its own git worktree,
while every build, test run and format check goes to the pool: lanq ships each worktree's HEAD plus its uncommitted
changes with no setup, so the dev PC only edits files and runs git. docs/PARALLEL.md covers the
worktree layout, allowlisting checkers such as dotnet format up front, counting max_jobs slots against agents,
running the full plan only after targeted tests pass, a local Docker worker, what sharding buys when compile time
dominates, and a short rule set for agents.
Most jobs need only --needs (capabilities, all required). In a pool of small and big machines two more options and
a plan file pick where a job may go; each only narrows the choice, and every other rule (capabilities, --mem, holds, allowed
hours, slots, wake) still applies:
--min-size heavy(that class or larger) or--size light,medium(one of these): by machine size. A machine's size is itssize:inmachines.ymlwhen it has one, else the probed class (light under 6 GB; heavy 16 GB or more with 4+ cores; else medium; see Sizing machines). Declaresize: mediumon a 16 GB laptop someone works on to keep heavy jobs off it, or a size on a machine that cannot report its memory. A machine of another size can never take the job (wrong_size), nor can one with no declared size that does not report its memory (size_unknown).--on big-01,build-01: only the named machines. An unknown name is refused (exit 2) before any network. A pinned machine that is busy or held makes the job wait (NoCapacity, retryable); one that can never take it ends the run at once (retryable: false).- A plan file,
lanq.yml, sets these per job, solanq run --plansends builds and unit tests to the small machines and the integration suite to the big ones in one command: docs/PLANS.md. - Since 0.10.0
--on,--sizeand--min-sizealso work with--plan. They narrow every job: a job's ownon:is intersected with--on, and its size classes with yours. They never widen a job. A job they leave with no machine ends the plan before anything is sent (NoCapacity, 75,retryable: false). The suggested rerun's--onlythen lists the jobs that can still run (never one whoseafter:prerequisite was narrowed out), replacing any--onlyyou gave; it leaves jobs out, so it is not safe for an agent to run unattended. A coding agent may narrow a plan, asks you before such a rerun, and never editslanq.ymlto widen a job.
lanq run --needs dotnet --size light,medium -- dotnet test tests/Unit -m:1
lanq run --needs dotnet --min-size heavy --shards 2 -- sh scripts/lanq/test-shard.sh tests/Integration
lanq health --needs dotnet --min-size heavy # which machines could take it, and why not the others
lanq run --plan --dry-run # what lanq.yml would do now
lanq run --plan --on big-01 --dry-run # the same, every job narrowed to big-01lanq health --json shows each machine's effective size and where it came from (sizeSource: probe or config);
for a machine with size: the text line adds both, for example (size: medium in machines.yml; probe: heavy).
Since 0.9.0 a job can set its own environment variables, for settings such as the build configuration or a test
filter. You decide which names jobs may set, in machines.yml:
policy:
allowed_env: [CONFIGURATION, TEST_FILTER, "MYAPP_*"] # exact names, or a prefix ending in *lanq run --needs dotnet --env CONFIGURATION=Release --env MYAPP_SEED=42 -- dotnet testThe job sees CONFIGURATION and MYAPP_SEED; with --shards every shard does. In lanq.yml the same is env:
(see docs/PLANS.md). The variables are set after the machine's own env:
and before lanq's LANQ_*, quoted as data like the machine's values.
What is refused, and why:
-
A name not in
policy.allowed_env(Rejected, 2, anask_developerstep): "--env TEST_FILTER is not in policy.allowed_env (your machines.yml)". The list is empty by default, so every--envis refused until you list names. A repository'slanq.ymlcomes with the code and can set only the names you allowed. -
A name on lanq's deny table (2), even when
allowed_envlists it. These variables can make an allowlisted command run other code, trust another server, or move where tools read their config:- the program loader and shell startup:
LD_*,DYLD_*,BASH_ENV,ENV,PS4,IFS,CDPATH,PATH, ...; - runtime startup hooks and module paths: Node (
NODE_OPTIONS,NODE_PATH), .NET (DOTNET_STARTUP_HOOKS,DOTNET_ROOT*,DOTNET_HOST_PATH,CORECLR_*,COR_*,COMPLUS_*), Java (JAVA_TOOL_OPTIONS,JAVA_OPTS,CLASSPATH, ...), Python (PYTHONSTARTUP,PYTHONPATH, ...), Perl and Ruby; - toolchains and build tools: Go (
GOFLAGS,GOROOT,GOPROXY, ...,CC,CXX,CGO_*), Rust (RUSTFMT,RUSTUP_TOOLCHAIN,RUSTC,RUSTDOC,RUSTFLAGS,RUSTDOCFLAGS,RUSTC_WRAPPER,RUSTC_WORKSPACE_WRAPPER,CARGO_ENCODED_RUSTFLAGS,CARGO_HOME,CARGO_TARGET_*,CARGO_BUILD_*,CARGO_REGISTRIES_*,CARGO_SOURCE_*), Gradle and Maven (GRADLE_OPTS,MAVEN_OPTS,MAVEN_ARGS),MAKEFLAGS,NUGET_PLUGIN_PATHS,DOTNET_MSBUILD_SDK_RESOLVER_*,MSBUILD*,GRADLE_USER_HOME,MAKEFILES; - TLS trust and proxies:
NODE_TLS_REJECT_UNAUTHORIZED,NODE_EXTRA_CA_CERTS,SSL_CERT_FILE,SSL_CERT_DIR,REQUESTS_CA_BUNDLE,CURL_CA_BUNDLE,HTTP_PROXY,HTTPS_PROXY,ALL_PROXY,NO_PROXY; - package indexes and interpreters: every name starting
PIP_, andUV_INDEX_URL,UV_EXTRA_INDEX_URL,UV_INDEX,UV_DEFAULT_INDEX,UV_FIND_LINKS,UV_PYTHON; - OpenSSL and glibc module paths;
- profile and temp folders:
HOME,USERPROFILE,APPDATA,LOCALAPPDATA,TEMP,TMP,TMPDIR,XDG_CONFIG_HOME, ...; - every name starting
GIT_,SSH_,NPM_CONFIG_,YARN_orLANQ_.
NODE_ENV,GOOSandGOARCHstay allowed. Anallowed_enventry the table fully covers (GIT_*,HOME) stops the config from loading (so doPIP_*,CARGO_BUILD_*,CARGO_REGISTRIES_*andCARGO_SOURCE_*); a prefix that only partly overlaps (NODE_*,UV_*,CARGO_*) loads, andlanq doctornotes it with anOKline:policy.allowed_env NODE_*: names on lanq's deny list (NODE_OPTIONS, NODE_PATH, NODE_TLS_REJECT_UNAUTHORIZED, ...) stay refused(fix: nothing to change if that is intended; list exact names to make it plain). The table is a guard against the obvious routes, not a sandbox. On the command line a deny-table hit is afix_commandstep ("this variable can never be set by a job; drop it or ask the developer"); fromlanq.ymlit isask_developer(the developer drops it from that job'senv:). - the program loader and shell startup:
-
A value that is empty, has control characters, is over 4,096 characters, or brings the job's variables over 16,384 in all (2). Windows PowerShell 5.1 cannot set an empty variable.
-
A value that looks like a secret (2, the value is never echoed), such as
MYAPP_PASSWORD=...or a token.--envis for settings, never secrets: values are visible to other users of the worker (its process list), the dry run prints them, and a suggested command innextStepsrepeats your command line, values included. The JSONenvfield andjobs.jsonllist names only.
Two cases rule out a machine rather than the job, both permanent and both judged from the config:
env_conflict: the machine's ownenv:inmachines.ymlsets the same name. Which value would win is a guess, so lanq does not use that machine for the job. If every machine that could take the job clashes, the run ends at once withNoCapacity(75,retryable: false) and anask_developerstep: "ask the developer: they can drop --env CONFIGURATION or remove it from the machine's env (build-01, big-01)".windows_command_too_long: on a Windows machine, lanq's largest job script for that machine plus the job's variables would pass the 8,000-character limit (the check uses the worst-case script, not the job's own arguments). The job goes to another machine; if none is left, it isRejected(2) with the length (and, when other machines were ruled out byenv_conflict, each of them and its variable), and the step isask_developer: "ask the developer: they can shorten or drop the --env values, or change machines.yml".
--dry-run shows the --env flags as given (after the secret scan) and every machine they rule out.
A job that needs a machine to itself (a benchmark, a load test, a suite that uses fixed ports) can take every slot:
lanq run --needs dotnet --exclusive --on big-01 --wait 3600 -- dotnet test tests/Perflanq claims slot-1 to slot-<max_jobs> on the machine, all or nothing, so no other lanq job, yours or anyone
else's, starts there while it runs. A claim that finds any slot taken removes the slots it just created and tries
again later. It also backs out when a live slot-N above its own max_jobs exists: another developer whose
machines.yml gives the same work_root a higher max_jobs is running a job there. That check is one look when the
claim is made: such a developer can still start a job in a higher slot afterwards, beside the exclusive job. Everyone
who shares a worker should use the same max_jobs for it.
- It waits for an idle machine. A machine with any live slot in use is
busyfor this job ("busy (slots 1/4; --exclusive needs all 4 free)"), and waiting can help. Stale slots (below) do not count. Nothing is reserved for it: other jobs keep taking free slots while it waits, so on a machine that is never idle it waits out--waitand endsNoCapacity(75). Pin it with--onto a machine that is idle, give it a long--wait, or run it in quiet hours. - With
--shardseach shard takes a whole machine.--shards autocounts the idle machines that can take the job; a fixed--shards Nabove the number of machines that can take it as configured (capabilities,size:,--env) is refused (2) before any network: "--exclusive --shards 6: only 4 machines can take this job". That count does not include--memor the Windows-arguments rule, so shards beyond what those leave wait for an idle machine. --mem, holds, hours, size and every other rule still apply. In a plan, the dry run marks the machine full, so a sibling job waits for another machine.
lanq unlock, the stale-slot reclaim and lanq health treat each of its slots as an ordinary slot.
Stale slots. A slot file more than 30 minutes (1,800 seconds) past its recorded deadline was left by a crashed
lanq. Since 0.9.0 the probe counts such slots separately (slots_stale=), and they do not make a machine busy, for an
exclusive job or any other: the next claim that passes them reclaims them. lanq health shows slots free 4/4 (4 stale: reclaimed by the next claim), health --json adds slotsStale (only when above 0) while freeSlots counts
live slots only, and a busy reason reads busy (slots 3/4, 1 stale: reclaimed by the next claim) (for an exclusive
job, busy (slots 2/4, 1 stale: reclaimed by the next claim; --exclusive needs all 4 free)).
When a claim reports that it could not reclaim a stale slot, lanq says so once per machine per run and counts that
machine's stale slots as busy for the rest of that run. The claim reports it (RECLAIM=STUCK slot-N) only when the
slot's .reclaim lock is older than about a minute (a dead reclaimer's), no lock could be made, or the file could not be
moved or deleted. A younger .reclaim lock is a reclaim in progress and is not reported, and a claim that simply
lost the slot to another job never marks the machine. The count in the line is the number of slots the claim named:
[lanq] build-01: 1 stale slot could not be reclaimed (a .reclaim lock or file permissions); counting it as busy for this run; lanq unlock build-01 clears it
The busy reason then reads busy (slots 2/2, 1 stale, not reclaimable) (for an exclusive job, busy (slots 1/2, 1 stale, not reclaimable; --exclusive needs all 2 free)); both stale notes can appear together. lanq health does not
change. A slot file above max_jobs that cannot be read counts as live, on Windows as on Linux.
A red run on your branch raises one question first: did my change break this, or was it broken already?
lanq run --needs dotnet --baseline -- dotnet test tests/UnitWhen the job ends Failed (its own non-zero exit), lanq runs the same request again (the same command, --dir,
--needs, size, --on, --env, --exclusive, --timeout) on the base commit, a clean tree without your
changes, and prints a verdict before the status line:
[baseline] [lanq] the job failed; running the same command at 1a2b3c4 (origin/main) to see whether the failure is new
[baseline build-01] ...
[lanq] baseline: at 1a2b3c4 (origin/main) the same command Failed (exit 1) on build-01 in 75.2s: this failure is pre-existing
[lanq] Next: the job exited 1; read logTail or the log (...) and fix the code; pre-existing: it fails at the base commit too (log: ...)
[lanq] log: /home/me/.local/state/lanq/logs/20261109-221503-a1b2c3.log
[lanq] Failed: exit 1
Here the merge-base is the tip of origin/main, so the base is named (origin/main); when your branch started
further back it reads (merge-base with origin/main).
- The base is the merge-base of HEAD and the default branch:
origin/HEAD, elseorigin/main,origin/master,main,master, the first that exists.--baseline-ref REF(a branch, tag or commit; it implies--baseline) uses the merge-base of HEAD and REF, so a branch that moved on still compares with where you started. On the base commit itself with uncommitted changes, the base is HEAD without them. - The verdict:
new(the base completed),preexisting(the base failed too, with any exit code),inconclusive(anything else: it timed out, found no machine, could not be read or sent, or you pressed Ctrl+C) orskipped(you are on the base commit with nothing uncommitted, so there is nothing to compare). - Information only. The run's status and exit code never change: a
preexistingfailure is stillFailedwith the job's own code. The verdict is in the[lanq] baseline:line, thebaselineobject in--jsonand thefix_codereason innextSteps. - When it runs: only after
Failed. Never afterTimedOut,WindowClosed,InfraError,NoCapacity,RejectedorCancelled, and never after a pass. - Shards: only the failed shards rerun, together, with the same
LANQ_SHARDandLANQ_SHARDS. The base's tests may split differently, so read a shard verdict as a hint. Plans: a job withbaseline: truethat failed reruns after the whole plan has ended; jobs skipped after it do not. - Where: the machine that failed, so that the verdict reflects the commit and not the machine. While that
machine could take the rerun but is busy, the rerun waits for it for up to 2 looks of about 15 seconds each, never
past what is left of its own
--wait, printing[lanq] waiting for a slot on build-01, where the job failed, before taking another machine (look 1 of 2). While other reruns of the same run hold slots the line is[lanq] waiting for a slot on build-01, where the job failed (the other baseline reruns hold some)instead. After that it takes any machine that can run it. With--wait 0, the default, it does not wait for that machine at all: it takes any machine that can run it now, and with none free it endsNoCapacity, which makes the verdictinconclusive. A machine that is held or can never take the job is not waited for. - Rerun lines are prefixed
[baseline]([baseline 2/4]for a shard,[baseline unit 2/4]in a plan). On another machine than the one that failed, the JSON hassameMachine: falseand the message ends(on big-01, not build-01 where it failed: the result may reflect the machine). - Ctrl+C: a rerun that has not started yet is
inconclusive: cancelled (Ctrl+C) before it started(in the JSON,statusnullif it had not begun,Cancelledand 130 if it was waiting for or claiming a slot); one that is running is stopped and cleaned up (inconclusive: cancelled (Ctrl+C); its cleanup ran,Cancelled, 130). The run still exits with the job's own code. - Cost: a red run takes about twice as long. That is why it is opt-in.
- Refused before anything is sent (2): a REF that is empty, over 256 characters, holds control characters,
starts with
-or contains..("--baseline-ref must name one branch, tag or commit (for example --baseline-ref origin/main or --baseline-ref v1.2.0)."); a REF that is not a commit; a repository with no commit yet; no default branch found; or a history with no common commit. A shallow clone (CI often fetches one) that lacks the merge-base is not refused, because the job itself can run: the baseline isinconclusive("could not find the base commit (shallow clone?)"). Fetch more history (git fetch --deepenor--unshallow) to get a verdict. - The base commit is sent like any snapshot, after the committed-name and package-config secret scans; a hit makes the
baseline
inconclusive("the base commit was not sent: Refused: possible secrets in payload (...)", the value never shown) and sends nothing. On an archive worker this sends the base commit's files: older files than your snapshot. - In
lanq.yml,baseline_ref:must name a branch or tag (it must resolve underrefs/heads/,refs/remotes/orrefs/tags/): a commit id,HEADor*_HEAD, and revision characters (~ ^ : @ { } \ * ? [and space) are refused withlanq.yml: job 'x' (line N): baseline_ref must name a branch or tag (a commit can be given on the command line with --baseline-ref). A repository's file should not be able to pick any old commit to send to a worker (an archive worker receives that commit's whole tree); you can still name any commit on the command line. How the keys combine is in docs/PLANS.md. --dry-runprintsBaseline: on failure, rerun at 1a2b3c4 (merge-base with origin/main) (a dry run runs nothing), or that it would be skipped. Reruns are recorded injobs.jsonlwithbaselineOfandcommit, and left out oflanq statsand--target-minutes.
The verdict is per job (or shard), not per test: a preexisting verdict means the same command failed at the base,
not that the same tests did. Read both logs when it matters.
lanq never stores or sends your key; it only calls ssh and scp. The aim is that a synced folder, a stolen
laptop or a leaked log cannot hand someone a way into your build machines.
- Prefer a passphrase-protected key held by ssh-agent. Omit
key_envinmachines.ymlandlanqpasses no-i; ssh uses whatever your agent holds (stillBatchMode=yes, so a missing identity fails fast instead of prompting). Create a key withssh-keygen -t ed25519and choose a passphrase. - Windows. The OpenSSH Authentication Agent service is disabled by default. From an elevated PowerShell:
Get-Service ssh-agent | Set-Service -StartupType Automatic, thenStart-Service ssh-agent, thenssh-add $env:USERPROFILE\.ssh\id_ed25519. Microsoft's guide suggests backing the key up somewhere safe and then deleting the plain file from the machine once it is in the agent. - Linux / macOS. Run an agent and
ssh-add ~/.ssh/id_ed25519;ssh-add -llists what is loaded andssh-add -t <seconds>limits how long a key stays loaded. To share one agent across logins on Linux, keychain works: puteval `keychain --eval id_ed25519`in your shell profile. - Hardware-backed keys.
ssh-keygen -t ed25519-skcreates a key whose secret lives on a FIDO2 token (touch is required by default). It needs a token and FIDO-capable OpenSSH on both ends, and a person to touch it, which suits interactive use better than unattended overnight runs. - If you must use a key file (
key_env): keep it out of every repository and out of synced folders (OneDrive, Dropbox, iCloud); restrict it (chmod 600 ~/.ssh/id_ed25519; on Windows, in PowerShellicacls <file> /inheritance:r /grant:r "${env:USERNAME}:F", in cmdicacls <file> /inheritance:r /grant:r "%USERNAME%:F"); and give it a passphrase.lanq healthwarns when a configured OpenSSH-format key file opens with an empty passphrase (checked withssh-keygen -y -P ""). Other key formats and-skkeys are not checked, so no warning is not a guarantee. - Use a dedicated low-privilege build user on each worker. Build tools run project code with that user's
rights, so give it nothing but its
work_root. On Windows, a standard (non-admin) user's keys go in~\.ssh\authorized_keys; administrator accounts useC:\ProgramData\ssh\administrators_authorized_keys. - Restrict the key on the worker in that user's
authorized_keys, for examplerestrict,from="<your-lan-subnet>" ssh-ed25519 AAAA... lanq-build.restrictturns off port, agent and X11 forwarding and PTY allocation, none of whichlanqneeds;from=accepts CIDR notation, so a stolen key is useless off your LAN. Replace the placeholder with your LAN subnet in CIDR form. - Secrets that are not the SSH key: PowerShell SecretManagement + SecretStore. Use them for the key
passphrase and any job tokens:
Install-PSResource Microsoft.PowerShell.SecretManagementandInstall-PSResource Microsoft.PowerShell.SecretStore(orInstall-Module), thenRegister-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault,Set-Secret -Name BuildToken -Secret "..."andGet-Secret -Name BuildToken(add-AsPlainTextonly where you must). It is not a home for the SSH key file: ssh wants a key file or an agent, while the vault stores strings,SecureString,PSCredential, byte arrays and hashtables for PowerShell to read back. Microsoft states these modules are feature-complete and receive security and critical fixes only.
Sources: Microsoft, key-based authentication in OpenSSH for Windows, Microsoft, SecretStore getting started, ssh-keygen(1), ssh-add(1), sshd(8).
lanq health # who is awake and idle?
lanq run --needs dotnet,linux -- dotnet test -c Release # exit code is the job's exit code
lanq run --needs dotnet --dir tests --wait 120 -- dotnet test # wait up to 2 minutes for a free machine
lanq run --needs dotnet --timeout 30 -- dotnet test # stop the job after 30 minutes (exit 124)
lanq run --needs gpu --dry-run -- dotnet test # which machine would take it, and why not the others?
lanq run --needs dotnet --min-size heavy -- dotnet test # only a heavy machine (--size light,medium, --on big-01)
lanq run --needs dotnet --env CONFIGURATION=Release -- dotnet test # a job variable (the name must be in policy.allowed_env)
lanq run --needs dotnet --exclusive --on big-01 --wait 3600 -- dotnet test tests/Perf # big-01 to itself, once it is idle
lanq run --needs dotnet --baseline -- dotnet test # on failure: was it already failing at the base commit?
lanq run --plan # every job of the repository's lanq.yml (docs/PLANS.md)
lanq stats # jobs, times and speed per machine and per command
lanq doctor --remote # is my setup right, and does each worker find its tools?
lanq makeready --ssh me@old-pc.lan --os windows # can this PC be a worker? (read-only, changes nothing)
lanq makeready --ssh build@old-pc.lan --os windows --setup # print its one-time setup (connects to nothing)
lanq makeready --ssh build@old-pc.lan --os windows --add --name old-pc # add it to machines.yml once it is READYYou own machines.yml and the allowlists. Edit them yourself (or with lanq makeready --add); nothing else should.
Coding agents are good at deciding what to build and test. They are wasteful at working out how to reach a
remote box on every turn: composing ssh commands, retrying, and pasting long logs back into the conversation, all
of which spends context. With lanq the agent runs one deterministic command and reads one exit code plus the
last lines of output. The remote mechanics, the allowlist and the cleanup live in code instead of being re-derived
in prose each time. (This is a qualitative argument; this repository does not publish a token measurement.)
lanq run --needs dotnet -- dotnet test -c Release > "${TMPDIR:-/tmp}/lanq-last.log" 2>&1; echo "exit=$?"; tail -n 40 "${TMPDIR:-/tmp}/lanq-last.log"On Windows PowerShell:
$log = Join-Path $env:TEMP 'lanq-last.log'; lanq run --needs dotnet -- dotnet test -c Release *> $log; "exit=$LASTEXITCODE"; Get-Content $log -Tail 40Better for agents, --json --log-tail 60 puts the result and the log's last 60 lines in one JSON object on stdout
(see JSON output). The job's output still streams to stderr, so drop it; lanq keeps every line in the
job's own log, whose full path is logPath:
lanq run --json --log-tail 60 --no-wake --needs dotnet -- dotnet test -c Release 2>/dev/null; echo "exit=$?"lanq run --json --log-tail 60 --no-wake --needs dotnet -- dotnet test -c Release 2>$null; "exit=$LASTEXITCODE"The agent keeps the exit code, status, logTail and nextSteps, and opens more of the file at logPath only when
the tail is not enough. Per-job logs live in lanq's own state folder ($LANQ_HOME, else a per-user folder), not in your
repository. (A .lanq/ folder in the repository is excluded from the snapshot.) Before a heavy run, lanq run --dry-run --json ... or lanq health --needs dotnet --json shows which machine would take it, without running it.
Using lanq with AI agents. AGENTS.md is the short, tool-agnostic rule set an agent reads;
docs/AGENTS-GUIDE.md covers setup, instruction-file snippets and a failure playbook; and
docs/JSON.md is the --json contract (every field, status and exit code). Running several agents at
once, one worktree each, on one quiet dev PC: docs/PARALLEL.md.
Ready-to-copy assets live in docs/agents/:
CLAUDE.md-snippet.md: rules to paste into your project'sCLAUDE.md.AGENTS.md-snippet.md: the same for a project'sAGENTS.md(Codex and others).skills/lanq/SKILL.md: a minimal Claude Code skill. Copy thelanqfolder to.claude/skills/in your project (or~/.claude/skills/for all projects).
The split is deliberate: the developer owns the config and allowlists; the agent only calls lanq run. Text in
CLAUDE.md or a skill is guidance the model follows, not enforcement (Claude Code's docs say to use a hook for
that). The hard stops are in lanq: it refuses commands outside your allowlist and permission-skipping flags. To
also keep the agent away from the config file, use Claude Code permission rules or a hook.
policy:
load_threshold: 0.80 # (0,1]; load average per core (Linux) or CPU% (Windows) above this = hold short
min_free_disk_gb: 5 # a machine with less free space on its work_root drive is held (default 5)
allowed_commands: [...] # argv must START with one of these token sequences, e.g. "dotnet test"
allowed_directories: [...] # relative to the repo root; "src" also allows "src/App"; "." allows only the root
machines:
- name: build-01 # letters, digits, - _
os: linux # linux | windows
ssh: user@host # no leading "-"
key_env: ENV_VAR_NAME # optional. Omit to use ssh-agent (no -i is passed). Else the NAME of an env var holding a key file path
work_root: /srv/lq # Linux: absolute path. Windows: a drive path such as D:/lq. Forward slashes, no spaces, no ".."
capabilities: [dotnet] # tags matched by --needs (all must be present)
max_jobs: 2 # concurrent jobs via slot files
transfer: git # optional: git (default, recommended; worker needs git) | archive (worker needs only tar)
allowed_hours: "22:00-07:00" # optional; one "[Days ]HH:mm-HH:mm" or a list, e.g. ["Mon-Fri 22:00-07:00", "Sat,Sun 01:00-09:00"]
priority: low # optional: low (default; nice/ionice or BelowNormal) | normal
min_free_mem_gb: 2 # optional; overrides policy.min_free_mem_gb for this machine
size: medium # optional: light | medium | heavy for --size / --min-size; default: the probed size (see "Routing jobs")
env: # optional; variables for the job process only (see "Old machines with little RAM")
NODE_OPTIONS: "--max-old-space-size=2048"
path_prepend: [/home/build/.cargo/bin] # optional; absolute directories put in front of PATH for the job
wake: # optional; Wake-on-LAN, see "Waking a sleeping worker"
mac: "aa:bb:cc:dd:ee:ff" # required inside wake:
broadcast: 10.20.30.255 # optional IPv4 literal, 255.255.255.255 or private/link-local only; default 255.255.255.255
port: 9 # optional; 7 or 9
wait_seconds: 120 # optional; 1 to 600Policy keys added in 0.4, with their defaults:
policy:
min_free_mem_gb: 1.0 # hold a machine with less available memory (GB)
max_mem_pressure: 20 # Linux PSI memory "some avg10" (%) above this holds the machine
window_grace_minutes: 15 # a job may run this long past the end of its machine's allowed_hours window
min_window_minutes: 10 # no new job on a machine whose window ends sooner than thisAdded in 0.7.0:
policy:
keep_logs_days: 30 # 0 to 3650; 0 keeps job logs for everAfter a run, at most once a day, lanq deletes its own per-job logs in the state folder's logs/ that are older than
this, and the oldest beyond 5,000 (see Local state).
Added in 0.9.0:
policy:
allowed_env: [CONFIGURATION, TEST_FILTER, "MYAPP_*"] # names a job may set with --env or lanq.yml env:; default noneExact names, or a prefix ending in *, compared ignoring case. A name on lanq's deny table can never be set, even
when listed, and an entry the table fully covers (GIT_*, HOME, anything LANQ_*) is a config error. See
Job variables.
A file named PAUSE in a machine's work_root holds that machine (see "Sharing a machine with the people who use it").
Unknown keys are an error (so a password: field is refused rather than ignored), and so is a duplicate key. A key
left without a value (max_jobs: ~, a bare wake:) is an error too, except allowed_hours, key_env and a
machine's min_free_mem_gb, where it means "not set"; to turn Wake-on-LAN off, leave wake: out. Config lookup: --config,
then $LANQ_CONFIG, then the per-user config folder (~/.config/lanq/machines.yml or %APPDATA%\lanq\machines.yml).
LANQ_HOME moves the state folder (job log, logs, scratch, bases.json); it defaults to a per-user folder outside any repository.
Each default below is enforced in code and covered by a unit test.
- Key-only SSH. Every ssh/scp call uses
BatchMode=yes,PasswordAuthentication=no,KbdInteractiveAuthentication=no,PreferredAuthentications=publickeyandStrictHostKeyChecking=yes. There is no password option anywhere in the config. - Command allowlist. Only argv beginning with a configured token sequence runs. Each argument is individually
quoted for the remote shell, so
dotnet test; rm -rf /as one argument is neither allowed nor interpreted. - Directory allowlist. Jobs run only in allowlisted, relative directories inside the job worktree;
.., absolute and drive-letter paths are refused. - Best-effort secret scan. The command line and the uncommitted overlay are scanned for private-key blocks,
AWS/GitHub/Slack/
sk-tokens, JWTs, bearer tokens, and password/secret/API-key style assignments (quoted, JSON, YAML,.envandPassword=...;connection strings). Files named like.env,*.pem,*.pfx,*.jks,id_rsa,*.tfvars,terraform.tfstate,.git-credentials,.aws/credentialsor*.local.ymlare refused by name. The names of all committed files in HEAD are checked against the same list (.env,.env.*,.envrc,id_rsa,id_dsa,id_ecdsa,id_ed25519,secrets.json,credentials.json,.git-credentials,.netrc,_netrc,terraform.tfstate(and.backup),*.pem,*.pfx,*.p12,*.key,*.ppk,*.kdbx,*.tfvars,*.jks,*.keystore;*.local.ymlonly when uncommitted), because a bundle or archive carries them. Committed and uncommitted.npmrc,.pypircand.yarnrc.ymlfiles are read instead (up to 64 KB; larger ones are refused unchecked) and refused only when they hold a literal credential: in.npmrca non-empty_authToken,_auth,_passwordorpassword(also the registry-scoped//host/:_authToken=form) that is not just an environment reference like${NPM_TOKEN}, in.pypirca non-emptypassword, in.yarnrc.ymla non-emptynpmAuthTokenornpmAuthIdent(or any other line naming them: flow style is refused even with a reference, so write a block mapping; an environment reference must be exactly${NAME}or${NAME?}, a${NAME:-default}counts as literal; a YAML comment after the value is ignored; an empty key whose value continues on a deeper next line, and a block scalar, are refused) (lines may end in CR, LF or CRLF); the refusal names the file and key, never the value. Obvious samples pass (names ending in.exampleor.sample, names containing.example., and anything under afixtures/ortestdata/folder). A hit refuses the job before anything is sent, and the message never echoes the value. If a scan pattern times out the job is refused (fail closed). Since 0.9.2 the content of uncommitted files git shows as binary is scanned too (a.gitattributes-difforbinaryentry hides a file from the diff, not from lanq; also UTF-16 text and real binaries): blobs are read by object id without filters or textconv, text up to 32 MB per file and 256 MB in all, the printable strings of a binary (8-bit, UTF-16 and UTF-32) up to 8 MB per file and 64 MB in all; in a modified file only new lines or strings count. Compressed or encrypted content (a zip, a.gz) is not unpacked, so a secret inside it is not seen. The diff of ordinary text files is scanned with its added and its removed lines; since 0.10.1 a private key replaced in place there (a new body under the same BEGIN line, which the diff does not show; only a block that ends in its END line within 8192 lines, holds only key material with a base64 line of 16 or more characters that has a digit,+or/, and changed between BEGIN and END, so code that handles PEM is never refused; see SECURITY.md for the forms recognised; a changed text file whose path is not valid UTF-8, or two changed paths that decode to the same name, refuse the job) is found too: changed text files with a-----BEGINline are compared with their old version (renames included), up to 32 MB per version, and refused like a new key, sample keys in tracked text files included (generate test keys when the tests run instead). A file over a cap (text_over_capfor such a text file) is not refused: it is named on stderr and inscanSkipped(JSON.md); an object git cannot produce refuses the job. Never rename, compress, move or re-attribute a file to get past the scan. This is a safety net, not a guarantee: apart from.npmrc,.pypircand.yarnrc.ymlit does not read the content of committed files, it does not look at files that were committed and later deleted (they are still in the history a bundle carries), and it cannot recognise every secret format. - Job variables are opt-in by name.
--env(andlanq.ymlenv:) can set only names you list inpolicy.allowed_env(empty by default), never a name on the hard deny table (loader, runtime startup, toolchain, profile andGIT_*/SSH_*variables; see Job variables), and eachNAME=VALUEgoes through the secret scan. Values reach the job as data, quoted like the machine'senv:. They are not secret-safe: other users of the worker can see them in its process list. - A plan file can only narrow what lands on your disk.
lanq.ymlfetch_maxandfetch_max_filesmay only lower the 200 MB / 500-file fetch limits (a larger value is refused), and there is nofetch_dirkey: only your own--fetch-dir,--fetch-maxand--fetch-max-filespick the folder or raise a limit (up to 2 GB / 5,000 files).--on,--sizeand--min-sizewith--planonly narrow the plan's jobs (0.10.0). - No permission-skipping agent flags. Any argument containing
dangerously,skip-permissions,bypassPermissions,--yolo,bypass-approvals,danger-full-access,approval_policy=neveror--ask-for-approval neveris rejected, even for an allowlisted command. - Isolation. One detached worktree (git mode) or one fresh extracted folder (archive mode) per job, removed afterwards. Gitignored files are never shipped.
- git on the worker runs no hooks and no transports. Every git call in the worker scripts passes
-c core.hooksPath=/dev/null(NULon Windows),-c core.fsmonitor=false,-c protocol.allow=neverand-c protocol.file.allow=never; only the fetch of the uploaded bundle re-allows reading that local file. It also passes-c core.attributesFile=/dev/nulland runs withGIT_CONFIG_NOSYSTEM=1andGIT_CONFIG_GLOBAL=/dev/null(git 2.32 or later;lanq doctor --remotewarns about an older git), and prepare recreates a cache whose own config holds anything but whatgit init --barewrites and deletes itsinfo/attributes. Tests plant hooks, a smudge filter, aninclude.pathand a global-config filter and check that none of them runs. - Archive extraction is checked before it happens.
lanqrefuses to create an archive with an absolute path, a..segment, a backslash or a name Windows cannot store; non-regular entries (symlinks, submodules) are skipped and reported, never archived. The worker uses only GNU tar or bsdtar (busybox tar is refused, because it hides hard links and rewrites paths in its listing), lists the archive first (tar -tzfandtar -tvzf) and refuses it, writing nothing, if any entry is absolute, contains..or a backslash, is anything but a file or directory, or is shown as a link (symlink or hard link). Windows workers call the built-inSystem32\tar.exeby full path; the health probe checks once that it accepts--no-acls --no-xattrs --no-fflags --no-same-owner --no-same-permissions(otherwise the machine is held), and Prepare then extracts exactly once with those flags, with no fallback or retry. Linux extraction runs with--no-same-owner --no-same-permissions. This is checked by tests that run the generated scripts against crafted hostile archives; it is a defence in depth for a trusted-network tool, not a sandbox. lanq makereadyis read-only and leaves nothing behind. The embedded lanq-makeready scripts are byte-identical to a release whose SHA-256 a test pins (updated only throughscripts/sync-makeready.sh, which checks the release'sSHA256SUMSand its build-provenance attestation). The script goes to the worker on ssh stdin and runs from memory. Its report is untrusted input: capped at 1 MB, parsed by a source-generated deserializer, checked against thelanq-makeready/v1schema, sanitised before display and never executed. The--tunescan (0.12.0) is read-only too and goes the same way; its report is capped at 256 KB and 64 items, checked againstlanq-makeready-tune/v1, sanitised, and its fix ids and security flags are lanq's own. The fix script is never built in, sent or run.- Fetched files are data from an untrusted worker.
lanq run --fetchnever runs, opens or extracts what it fetches (there is no archive: each file comes as a header, base64 lines and a SHA-256). The worker script sends only regular files whose real path is inside the job folder and never follows a link;lanqthen checks everything again itself: each path (no.., absolute or drive paths, backslash,:, control or invisible characters, Windows device names such asCON,NUL.txtorNUL .txt, trailing dots or spaces, overlong names, and no two names that differ only in case), that it matches a pattern you asked for (in linear time: a crafted name cannot make the matcher hang), the file count and size caps on the bytes actually received, the exact size announced and the hash. Only stdout carries files; stderr is a separate, sanitised diagnostic. A file that fails any check is deleted and listed. Files are written under a short.lanq-partial-Nname, created new, and renamed (never overwriting) only below<out>/<job id>/once complete; nothing is written through a symlink or junction anywhere from the repository top (or--fetch-dir) down, so a.lanqlink committed in a repository is refused. Tests run the real scripts against links to/etc/passwd, symlink loops, junctions, names with newlines and FIFOs, and feed the receiver size lies, bad hashes,..paths, device names and case collisions. - Wake-on-LAN is opt-in per machine. A magic packet is unauthenticated, LAN-only UDP: anyone on the LAN who knows
the MAC address can send the same packet, so it is safe only because waking a PC is all it does.
broadcastmust be an IPv4 literal that is 255.255.255.255 or private or link-local (config load refuses anything else). - No telemetry, no network access except the SSH hosts you configure (and, for a machine with
wake:, one UDP broadcast packet to its configured broadcast address;lanq doctorwithout--remoteuses none).
See SECURITY.md for what this does not protect against.
- The secret scan is pattern-based and best effort. Committed files are checked by name only (in HEAD), not by
content (except
.npmrc,.pypircand.yarnrc.yml), and older commits are not scanned at all. A git bundle carries the repository's full history the first time a machine sees the repository (later bundles carry only new commits), so a secret that was ever committed and then deleted still reaches the worker; rewrite that history (and rotate the secret) or usetransfer: archive, which sends only the current files (a--baselinererun sends the base commit's files). It is a safety net, not a guarantee. - The allowlist limits what
lanqwill start, not what an allowlisted program does. Build and package tools such asdotnet test,dotnet build,npm testandnpm ciexecute project code (test code, MSBuild targets, npm lifecycle scripts) with the remote user's rights. Only run code you trust, and use a dedicated low-privilege account on the remote machines. - Cancellation and timeouts: cleanup kills the job's process group (Linux) or PowerShell process tree (Windows)
recorded in
locks/job-<id>.pidbefore removing the worktree. This is best effort: it needs the machine to be reachable when cleanup runs (on Windows the pid file also names the job's child process, and a process is killed only when its start time matches the recorded one, so a reused pid is safe; on Linux the pid file also records the group leader's start time and the boot id, every job process carriesLANQ_JOB=<job id>in its environment, and the group is signalled only in the same boot and only when the leader still has that start time, or the leader is gone and a live member of the group carries this job'sLANQ_JOB). If it is not, the worker stops the job itself one minute after its limit (Linux undertimeout, where that command exists and works; Windows by a deadline wait that ends the job's Windows job object, which also takes down the job's whole tree if the wrapper itself dies). A job that deliberately starts work outside its own tree (a new session or process group on Linux, a scheduled task or service on Windows) can escape this. - Windows remote commands are passed as an encoded command line limited to 8000 characters; very long argument
lists are refused with a message giving the limit and the actual size. A Windows machine whose
env:andpath_prepend:alone would already pass that limit in the job script is refused when the config loads, with the machine, the settings and how much is over;lanq doctor --remotereports its own script's overflow as a FAIL line. A job's--envvalues count too: a Windows machine they push over the limit is not used for that job (windows_command_too_long). - In git mode the first job on a machine sends the full history of HEAD; later jobs send only what that machine does not have yet (see "Incremental bundles"). Archive mode sends the whole working snapshot each time, with no history and no cache.
- A crashed orchestrator can leave a slot file behind. Each slot file records its own deadline (the job's
--timeoutplus 40 minutes for transfer and cleanup, on the worker's clock), and a slot more than 30 minutes past it is reclaimed by the next claim that passes it (its job is killed first if it is somehow still running); until then it does not count as in use (see Stale slots). Slot files written by lanq before 0.4 carry no deadline and are never reclaimed: deletelocks/slot-N(and any stalelocks/job-*.pid) under the machine'swork_root. - No persistent queue:
--waitpolls every 15 seconds. - Plan files (
lanq run --plan) pass nothing between jobs: each job runs in its own throw-away folder, maybe on another machine, andafter:only orders jobs (a test job builds what it needs itself). - A plan's fetches have no plan-wide total: at worst a plan writes the number of fetching jobs times the per-job limit
(32 jobs at the 200 MB default: 6.4 GB).
lanq.ymlmay only lower that limit; only your own--fetch-maxraises it. lanq statsknows a plan by its file's full path, so clones of one repository in different folders are separate rows.--exclusivehas no reservation: it waits until a machine happens to be idle, and other jobs keep taking free slots meanwhile, so on a busy pool it can wait out--wait. Its check for slots above its ownmax_jobsis one look at claim time, so everyone who shares a worker should use the samemax_jobsfor it.--baselinecompares jobs, not tests: it says whether the same command failed at the base commit, not whether the same tests failed. With--shards, the base may split its tests differently.- Wake-on-LAN is best effort and was exercised only against fakes and a loopback UDP socket, not real hardware.
lanqcannot know whether a packet woke anything beyond the machine answering ssh later. The automatic wake judgesallowed_hourson your PC's clock (an asleep worker cannot report its own), so keep both in the same time zone. - Windows workers never take a job whose arguments contain any of
"<>^%. PowerShell 5.1 passes embedded double quotes through unescaped, and.cmdshims such asnpm.cmdre-parse the command line throughcmd.exe, so such an argument could run a second command.&and|(as indotnet test --filter "Category=Unit|Category=Arch") are allowed only when the program is a native.exe: the command must be a bare name or path with no extension or.exe(not.cmd,.bat,.ps1, notcmd,npm,npx,yarnorpnpm), and the worker checks before starting anything that the name resolves there, with the job's own PATH andpath_prepend:, to an.exe. If it finds a.cmdor.batinstead (say adotnet.cmdearlier on PATH), nothing runs and the job isRejected(exit 2) naming what it found: call the.exedirectly or put the command in a script. A job Windows cannot take skips Windows workers (hold reason "arguments not safe for Windows (...)") and runs on a Linux worker; it is refused (exit 2) only when no Linux worker has the needed capabilities. allowed_hoursuses the worker's clock. Across a daylight-saving change the window end is placed with the UTC offsets the worker reports on every UTC quarter hour for the next 36 hours (an end time that happens twice counts as the earlier one); a Linux worker whosedatecannot print the offset of another instant (date -d @EPOCH +%z) falls back to plain local time, which can be an hour longer or shorter that night. A PAUSE file,allowed_hoursand the memory holds only stop new jobs from starting; a running job is stopped only by--timeoutor by the end of its window plus the grace period. In tests the generated Linux scripts are checked withsh -nand the Windows scripts with the PowerShell parser, but only when those shells exist on the machine running the tests (otherwise those checks are skipped), and the scripts have so far been exercised only against fakes plus a local process-group test; report any real-host defects.
Desktop apps such as Orca are interactive: you watch and steer many coding agents, each in its own worktree, from a GUI, with diff review and PR integrations. LanQueue is a different shape: a headless command that routes one job at a time to a machine by capability and load, with a policy file in front of it. It does not run or supervise agents interactively, has no UI, and installs nothing on the remote machines. They can complement each other; choose by whether you want a cockpit or a dispatcher. (Feature descriptions are based on each project's public README at the time of writing; check the project for current details.)
lanq's repository runs its own test suite through lanq on Windows workers: lanq.yml has a guard job
(scripts/lanq/check-test-split.ps1, which fails unless every test lands in exactly one shard) and the suite in two
Windows shards, each rerun at the base on failure (baseline: true), with a fixed shard count so history compares
like with like. The shard scripts are the SHARDING.md recipe. lanq run --plan --json --no-wake is the release gate's "full suite on the pool"; it needs lanq 0.11.0 or later (unit-windows has
results:, which an older lanq refuses). Your machines.yml must allow exactly these commands, and tag the workers
windows:
policy:
allowed_commands:
- "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/lanq/dotnet-test-shard.ps1"
- "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/lanq/check-test-split.ps1"A Linux job (four shards and its own guard, on workers tagged linux) is in lanq.yml as a commented block: a plan
file has no conditions, so a job for an OS the pool lacks could never run and would fail the plan. With Linux workers,
uncomment it and also allow "sh scripts/lanq/dotnet-test-shard.sh" and "sh scripts/lanq/check-test-split.sh". CI
runs both guards (Linux and Windows) on every pull request. Never a bare sh or powershell. An agent may run the
plan; it never edits lanq.yml or the scripts to turn a red run green, and never edits machines.yml.
Before a release, scripts/smoke-workers.ps1 runs the release candidate's binary on real workers with a separate
smoke config, machines.smoke.yml, in the same per-user folder as machines.yml: %APPDATA%\lanq\machines.smoke.yml on Windows, ~/.config/lanq/machines.smoke.yml (or $XDG_CONFIG_HOME/lanq/machines.smoke.yml) elsewhere (see RELEASING.md, step 1b). It refuses the real
machines.yml, uses a temporary LANQ_HOME, and needs the smoke machines to equal the real ones. Agents run it only
when asked, and never edit either file.
See CONTRIBUTING.md and the CHANGELOG. MIT licensed, see LICENSE.
