LanQueue 0.9.2
See the version list below for details.
dotnet tool install --global LanQueue --version 0.9.2
dotnet new tool-manifest
dotnet tool install --local LanQueue --version 0.9.2
#tool dotnet:?package=LanQueue&version=0.9.2
nuke :add-package LanQueue --version 0.9.2

LanQueue
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. Your old machines can still help you get development done: all a worker needs is a
LAN connection, SSH, git and the toolchain for your jobs, and it joins your queue. No git on the old PC? Set
transfer: archive and it needs only SSH, tar and your toolchain. Your dev PC stays free for writing code.
Install
dotnet tool install --global LanQueue
dotnet tool update --global LanQueue
Requires the .NET 10 SDK on the machine you run lanq from, plus git and ssh on the PATH.
No .NET SDK? Each GitHub release also has a single-file native lanq for Windows (x64, Arm64), Linux (x64, Arm64,
glibc 2.27 and later) and macOS (Apple silicon), with SHA256SUMS, build-provenance attestations and a Scoop
manifest: https://github.com/jangolath/lanqueue#install
Quick start
- Write a starter
machines.ymlwithlanq init(or start from the example), list your machines, and make sure key-based SSH login works. - Check your setup and the fleet:
lanq doctor --remote, thenlanq health - Run a job from inside a git repository:
lanq run --needs dotnet,linux -- dotnet test -c Release - Bring results back: add
--fetch 'TestResults/**/*.trx'(repeatable) and the matching files land in.lanq/artifacts/<job id>/, whether the job passed or failed.
Onboarding a PC: lanq makeready --ssh user@old-pc.lan --os windows runs the read-only
lanq-makeready check over SSH (built in, sent on stdin, nothing written to
the PC) and suggests a machines.yml entry; lanq makeready --all checks every configured machine and prints one
summary table (--json for one object). lanq unlock <machine> clears slots left by a crashed run.
For scripts and coding agents, run, health, doctor, stats, makeready, init and wake take --json and
print one object with suggested nextSteps. lanq run --dry-run shows where a job would go without sending it,
lanq doctor --json lists each check with its fix, lanq stats --json gives pass rates and run times per machine and
per command, and --shards auto --target-minutes 10 sizes shards from earlier runs. See
docs/JSON.md and
AGENTS.md.
lanq picks the least loaded machine that has what the job needs, ships your current git state (including
uncommitted changes) to a throw-away worktree, runs the one allowlisted command, streams the log back and cleans up.
lanq's exit code is the job's own exit code; 2 means rejected by policy or bad arguments, 70 an infrastructure
error, 75 no eligible machine and 124 that the job ran past --timeout <minutes> (default 240) and was stopped.
A job that itself exits with 124 looks the same; the [lanq] TimedOut: ... status line on stderr tells them apart.
Setting up a pool for a team (one orchestrator, Windows 10/11 and Linux workers, low-RAM micro PCs, overnight family PCs)? Follow the team quick start.
What a worker needs
An SSH server, the toolchain your jobs use, and git (recommended, the default) or, with transfer: archive, just
tar (the built-in bsdtar on Windows 10 1803+; GNU tar or bsdtar plus gzip on Linux, busybox tar is refused). Nothing from lanqueue is installed on it, and it needs no GitHub
access. Setup steps for Linux and Windows: docs/WORKERS.md.
Lend it a shared or old PC
allowed_hoursper machine, by day:["Mon-Fri 22:00-07:00", "Sat,Sun 01:00-09:00"], on the worker's own clock. A job still running when the window ends is stopped after a grace period (exit 124,[lanq] WindowClosed).- Optional Wake-on-LAN per machine (
wake: {mac: "aa:bb:cc:dd:ee:ff"}):lanq runwakes one sleeping machine only when no awake one can take the job (needs--wait,--no-waketurns it off),lanq health --wakewakes sleepers, both only insideallowed_hourswith at leastmin_window_minutes+wait_secondsof the window left;lanq wake <machine> [--wait] [--json]wakes it on request. Needs Wake-on-LAN enabled in the BIOS/UEFI and the NIC driver, usually wired Ethernet; see docs/WORKERS.md. - A
PAUSEfile (Linux:PAUSEorpause) in the worker'swork_rootholds the machine; anyone at that PC can create or delete it. A job already running is not affected. - Jobs run at low priority by default (
nice/ioniceon Linux, BelowNormal on Windows);priority: normalturns it off. - Machines with little free memory are held (
min_free_mem_gb, Linux memory pressure), andlanq run --mem 4asks for a machine with at least 4 GB available. - Per-machine
env:(for exampleNODE_OPTIONS: "--max-old-space-size=2048") andpath_prepend:(for nvm, pyenv, rustup or sdkman tools a non-login SSH session cannot find).
Split long work across the pool
lanq run --shards 4 -- npx jest --shard={shard}/{shards} runs four pieces at once on free slots (--shards auto
uses every free slot that can take the job); each gets {shard}/{shards} in its arguments and LANQ_SHARD/
LANQ_SHARDS in its environment, and the snapshot is built once. Exit 0 only if every shard passed; --json prints
one object with a shards array. lanq health shows cores, total RAM, free slots and what each machine suits.
Recipes for .NET, Node, Python, Go and Rust:
docs/SHARDING.md.
Route jobs and run a whole plan
--min-size heavy or --size light,medium sends a job only to machines of that size (probed, or size: in
machines.yml), and --on big-01 only to named machines; every other rule still applies. A repository's lanq.yml
lists its jobs (build, unit tests, integration tests, a serial tail with after:), each one lanq run line, and
lanq run --plan runs them side by side on one snapshot with one result (--only, --dry-run, --json):
docs/PLANS.md.
Per-job options
--env NAME=VALUEsets a variable for one job, for names you list inpolicy.allowed_env(none by default); a deny table (loader, runtime startup, toolchain, profile,GIT_*andSSH_*variables) wins over that list. Settings only, never secrets.--exclusivetakes every slot of the machine, so nothing else runs there; it waits for an idle machine.--baselinereruns a failed job at the base commit (the merge-base with the default branch, or--baseline-ref) and says whether the failure isneworpreexisting; the exit code stays the job's.
Safe by default
- Key-only SSH with strict host-key checking; there is no password option.
- Only commands and directories you allowlist can run; arguments are quoted, never interpreted by a shell (Windows
workers never take arguments containing
"<>^%, nor&|unless the program is a native.exe, sincecmd.exeshims would re-parse them). - Worker output is untrusted: control, bidi and zero-width characters are shown as
?. --fetchtreats the worker as untrusted: regular files only (links never followed), sent as checksummed text (no archive is ever extracted), every path, size, count and hash checked again locally, files created new below.lanq/artifacts/<job id>/and never through a link. Fetch problems are reported but never change the exit code.- Best-effort secret scan of the command and uncommitted changes, plus the names of committed files (
.env,id_rsa,*.pemand similar) and the content of.npmrc,.pypircand.yarnrc.yml, before anything leaves your machine. - On git workers, git runs with hooks off, transports refused and the system and global git config ignored (git 2.32+), and a tampered cache is recreated; later jobs send only new commits.
- No daemon, no telemetry, and no network access except the SSH hosts you list.
More
MIT licensed.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.12.0 | 99 | 11/14/2026 |
| 0.11.0 | 97 | 11/14/2026 |
| 0.10.1 | 92 | 11/14/2026 |
| 0.10.0 | 97 | 11/13/2026 |
| 0.9.2 | 91 | 11/13/2026 |
| 0.9.1 | 95 | 11/13/2026 |
| 0.9.0 | 93 | 11/13/2026 |
| 0.8.1 | 98 | 11/10/2026 |
| 0.8.0 | 87 | 11/10/2026 |
| 0.7.0 | 93 | 11/10/2026 |
| 0.6.0 | 88 | 11/10/2026 |
| 0.5.1 | 90 | 11/9/2026 |
| 0.5.0 | 90 | 11/9/2026 |
| 0.4.0 | 96 | 11/9/2026 |
| 0.3.1 | 91 | 11/9/2026 |
| 0.3.0 | 85 | 11/8/2026 |
| 0.2.0 | 98 | 11/8/2026 |
### Security
- The secret scan now reads the content of uncommitted files git shows as binary, which the diff it scanned before
only reported as "Binary files ... differ": files a `.gitattributes` entry (`-diff`, `binary`) hides from diffs,
UTF-16 text, files with a NUL byte and files over `core.bigFileThreshold`. The paths come from
`git diff --cached --numstat`, their object ids from `git diff --cached --raw --no-renames`, and the blobs are read
locally with `git cat-file --batch` (never with filters or textconv, so no attribute driver runs). Text (UTF-16 with
a byte order mark, or text with no NUL byte in its first 8000 bytes) is scanned up to 32 MB per file and 256 MB per
snapshot, plus its printable strings when it holds a NUL or a byte order mark; a real binary has its printable
strings (8-bit, UTF-16 and UTF-32 runs of 4 or more characters) scanned, up to 8 MB per file and 64 MB per snapshot.
The caps are decided from git's sizes and a file's first 8000 bytes, so a file over a cap is never read whole. In a
modified file only lines or strings the old version did not have count. Texts are scanned in line-cut chunks of
about 1 MB; each starts with the previous chunk's last 64 non-blank lines (blank lines between them included). A
pattern timeout still refuses the run. A binary path git does not list, or an object it cannot produce, refuses the
run (`scan-incomplete`, with a hint to check the repository with `git fsck`). Symlinks, submodules, deleted files and
mode-only changes read nothing. Compressed or encrypted content is not unpacked.
- `lanq makeready --json`, each `--all --json` row and `--add --json` now print the worker's report through one
output-only wrapper: every string is sanitised (control, bidi and zero-width characters become `?`, keys of
`suggestedMachine.env` included), as JSON.md always promised; before, the JSON paths printed them as the worker
sent them. `suggestedMachine.path_prepend` and `env` are kept only when the text and `--add` would use them (exactly
one usable folder, `env` exactly `DOTNET_ROOT` set to it).
- lanq's own Linux safe-folder rule (the toolchain search of `lanq doctor --remote` and `lanq makeready --add`, before
a folder is proposed for `path_prepend:`) now reads POSIX ACLs, exactly as lanq-makeready 0.4.1: `getfacl -cpn` (at
most 5 s); a named `user:ID`/`group:ID` entry whose effective rights include write, or a `default:` entry whose own
rights do, for an ID other than root, the build account or its private group, makes the folder open; so do
`getfacl` failing and output with no `user::` line. Without `getfacl`, `ls -ld` failing or showing the `+` ACL marker
(or a missing marker column) is open, and with BusyBox `ls` any group write is. Parent folders are checked unless they
are links or sticky. macOS is not checked. Before, a folder writable by another account through an ACL was proposed.
### Behaviour changes
- `lanq makeready` runs lanq-makeready 0.4.1 (embedded, SHA-256 pinned): its safe-folder check reads POSIX ACLs, so a
`path_prepend` suggestion may now be left out (and listed in `lanqWithheld`, or the text's comment) where 0.4.0
proposed it. A folder lanq or lanq-makeready calls open is reported, never proposed; install the `acl` package on a
Linux worker that uses ACLs, or the folder stays open.
- A run 0.9.1 accepted may now be `Rejected` (2) for a secret in such a file. The finding names
`uncommitted file <path> (binary per git)`, never the value, and the message adds: "A file git shows as binary is
read anyway: a .gitattributes entry (-diff or binary) hides a file from diffs, not from lanq; take the secret out of
the file." An agent must not rename, compress, move or re-attribute the file to get past the scan.
- A file over a cap is not refused. It is named on stderr (`[lanq] secret scan: N file(s) not read in full: ...`, at
most 5) and listed in the new conditional `scanSkipped` key (`path`, `bytes`, `reason`: `binary_over_file_cap`,
`binary_over_total_cap`, `masked_text_over_cap` or `masked_text_over_total_cap`) of `lanq run --json`, at the top level of `--shards` and
`--plan`, and in both dry runs, whose snapshot line also notes the count. Report it; do not try to "fix" it.
- In `lanq makeready` JSON, `suggestedMachine.path_prepend` and `env` may now be absent where 0.9.1 printed them (a
list, a redacted home folder, a mismatched or extra variable, or characters lanq refuses). Both keys were always
optional. What was left out is listed in the new conditional report key `lanqWithheld` (`key`, `reason`), which is
lanq's own: a worker that sends one is ignored. The schema stays `lanq-makeready/v1` and the report still has no
`nextSteps`. `suggestedMachine` is advice for the developer; an agent never writes it into `machines.yml`.
### Docs
- The .NET shard recipe in docs/SHARDING.md split classes by their position in a sorted list, and `sort -u` /
`Sort-Object -Unique` sort by the machine's locale or culture: shards on machines with different locales could run
some classes twice and others never while the run stayed green. A class now goes to shard
`cksum(class) mod N + 1` (the POSIX `cksum` of its full name), identical in sh and PowerShell on every locale, and a
class keeps its shard when others are added. If you copied the old scripts, replace them. The recipe also gains a
guard script (`check-test-split.sh PROJECT N`) that fails unless every test lands in exactly one shard, and the
durations recipe's sorts are now ordinal (`LC_ALL=C`, `[StringComparer]::Ordinal`).
- README (security model, `lanq makeready --json`, a new "Developing lanq" section with the allowlist lines),
SECURITY.md, docs/JSON.md (`scanSkipped`, `lanqWithheld`), PLANS.md, SHARDING.md, CONTRIBUTING.md and the AI guide
(AGENTS.md, docs/AGENTS-GUIDE.md, both snippets, the skill, llms.txt): an agent never adds a `.gitattributes`
entry, renames, compresses, moves or re-encodes a file (or moves a secret into a `-diff` file) to get past the scan;
it reports `scanSkipped` and `scan-incomplete` instead of fixing them; it never writes `suggestedMachine` into
`machines.yml`; it may run lanq's own plan but never edits `lanq.yml` or its scripts to turn a red run green; and it
runs the release smoke only when asked, never editing `machines.yml` or `machines.smoke.yml`.
### Project
- lanq's repository has its own `lanq.yml`: a PowerShell `guard` job and two Windows shards of the test suite,
running the scripts in `scripts/lanq/` (the same files as the SHARDING.md recipe), plus a commented Linux job for
pools with Linux workers (a plan has no conditions, so a job no machine can take would fail it). It names no
machines. CI runs the split guard on Linux (sh) and Windows (PowerShell).
- `scripts/smoke-workers.ps1` (Windows PowerShell 5.1 and PowerShell 7) smokes a release candidate on real workers,
as RELEASING.md's new step 1b: it runs the release dry run's `native-win-x64` binary (checked by the run's `headSha`
against the release branch), with the owner's separate `machines.smoke.yml` and a temporary `LANQ_HOME`. It needs
`-Branch` (never the default branch), a successful `release` workflow_dispatch run at that branch's head, and a
binary whose `--version` carries `+<headSha>`. It refuses the real config (`LANQ_CONFIG` and the per-user file, by
resolved path or the same SHA-256) and checks it is unchanged, refuses unless the smoke machines' `ssh`, `work_root`
and `max_jobs` equal the real ones, and prints a PASS/FAIL/SKIP/N/A table: exit 0 only when every scenario that
applies passed (N/A: no machine of that kind in the smoke config; a skip fails unless `-AllowSkip`). Agents run it
only when asked.
Full changelog: https://github.com/jangolath/lanqueue/blob/main/CHANGELOG.md