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

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.
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 |
### Routing
- `--min-size light|medium|heavy` (that class or larger) and `--size C[,C]` (one of these classes) on `lanq run`
(single, `--shards`, `--dry-run`) and `lanq health`. They do not go together. A machine's size is its `size:` in
`machines.yml` when it has one, else the probed class (under 6 GB light; 16 GB or more with 4 cores heavy; else
medium).
- Optional machine key `size: light|medium|heavy`: declare a 16 GB laptop `medium` to keep heavy jobs off it, or a
machine whose memory cannot be probed. Without it nothing changes.
- New permanent reason codes `wrong_size` (the machine's size does not match) and `size_unknown` (no declared size and
no reported memory). A declared size is judged from the config alone, so a job no machine can ever take for its
size ends at once with 75 and `retryable: false`, before any ssh.
- `--on m[,m]` on `lanq run` (also `--shards`, `--dry-run`) and `lanq health`: only these machines, matched ignoring
case; an unknown name is refused (exit 2) before any network. It only narrows: capabilities, size, `--mem`, holds,
allowed hours, slots and wake rules all still apply. A pinned machine that is busy or held is `NoCapacity`
(`retryable: true`, waits out `--wait`); one that can never take the job ends at once (`retryable: false`).
Suggested next steps keep `--on`, `--size` and `--min-size` and never drop them.
### Plan files
- `lanq run --plan` runs the jobs of `lanq.yml` at the repository top (`--plan-file PATH` for another file):
`version: 1`, optional `defaults:`, and up to 32 `jobs:`, each one `lanq run` line (`command`, `dir`, `needs`,
`mem`, `size` or `min_size`, `on`, `timeout`, `shards`, `target_minutes`, `shard_retries`, `fail_fast`, `fetch`)
plus `after:` to order them. Jobs run side by side on one snapshot of the repository and give one result.
- Every job is checked as its own `lanq run` line before anything is sent (allowlist, allowed directories, flags,
command-line and payload secret scans, the Windows rule): one refusal refuses the plan (2), and a job no machine can
ever take ends it with 75 before the snapshot.
- A job whose `after:` job did not complete is `Skipped`. Others keep running unless `--fail-fast` (running jobs are
cancelled and cleaned up, the rest skipped). `--wait` counts only while no job of the plan holds a slot.
- `--only a,b` runs only those jobs; `--dry-run` prints each job's equivalent `lanq run` line and what it would do now
(`WouldRun`, `WouldWait`, `Pending`, `NoCapacity`), sending nothing; `--json` prints one object with a `jobs` array.
Exit 0 only when every job completed, else the first failed job's own code, then 2, 124, 70, 75, 130.
- `lanq.yml` has no keys for hosts, ssh, keys, env, paths, wake, priority or policy: unknown keys are refused with the
line and a did-you-mean, and machine settings are pointed back to `machines.yml`. YAML anchors, aliases and merge
keys are refused (share values with `defaults:`). A job can do nothing its `lanq run` line could not.
- Guide: https://github.com/jangolath/lanqueue/blob/main/docs/PLANS.md
### Windows workers
- `&` and `|` in arguments are allowed when the program is a native `.exe` (`dotnet test --filter "A|B"`): a bare name
or a path with no extension or `.exe`, not `cmd` or a package-manager shim (`npm`, `npx`, `pnpm`, `yarn`,
`corepack`). The worker checks again before starting anything: when the name resolves there (with `path_prepend:`)
to anything but an `.exe`, nothing runs and the job is `Rejected` (2) naming what it found. `"` `<` `>` `^` `%` stay
refused for every program.
- Workers whose build account is denied WMI/CIM now work: memory falls back to .NET (`GlobalMemoryStatusEx`), load to
two `GetSystemTimes` samples, and with no source at all `lanq health` shows `load ?` and load never holds the
machine. Each job runs in a Windows job object, so a timeout, Ctrl+C, a stale slot or cleanup ends the whole process
tree without WMI (`taskkill` stays the fallback).
- `lanq doctor --remote` shows a `wmi` WARN for such a worker, with what the owner could grant.
### Setup
- `lanq init` without `--config` writes the per-user config file lanq reads without flags
(`%APPDATA%\lanq\machines.yml`, `~/.config/lanq/machines.yml`), creating the folder; never the current folder.
- When the `dotnet` check fails (`dotnet --version` now needs an SDK: a runtime-only install counts as missing),
`lanq doctor --remote` searches the worker's usual and private install folders (read-only, about five seconds) and
names the `path_prepend:` and `DOTNET_ROOT` lines to add; `lanq makeready --add` proposes them in the entry it shows.
lanq still never edits a config or a worker's `PATH` by itself.
### Behaviour changes
- `lanq health --json`: `size` is the effective size (the machine's `size:` when set, else the probe), and every row
gains `sizeSource` (`probe` or `config`) and `loadKnown` (`false` when the worker could not measure its load). The
text line changes only for a machine with `size:` (`(size: medium in machines.yml; probe: heavy)`).
- `jobs.jsonl` lines of a plan run gain optional `planJob` (the job's name) and `planRun` (shared by one plan run);
`v` stays 2.
- Jobs of a plan run get `LANQ_PLAN_JOB=<name>` in their environment.
- On Windows, processes a job leaves running (build servers, for example) now end with the job.
- `lanq init` no longer writes `./machines.yml` (see Setup).
- Loading a config now checks the Windows job script at its largest (a job given `&` or `|`, the longest plan job
name), so a Windows machine whose `env:` leaves no room for such a job is refused at load instead of at run time.
- With no per-user config folder (no usable `HOME`/`APPDATA`), `lanq init` and config lookup exit 2 and name
`--config`/`LANQ_CONFIG`; a relative `XDG_CONFIG_HOME` is ignored.
### Security
- Windows workers run lanq's helper script (`work_root/bin`) only when its SHA-256 matches lanq's own copy, and lanq
rewrites it before each job if it changed, so a job cannot plant code in later jobs' wrapper, stop, cleanup or doctor
scripts, or stop a cleanup before it frees the slot.
- The job wrapper's `LANQ_EXIT` and `LANQ_WINARGS` lines carry a per-run random value that is not in the job's
environment, so a job that prints them is ordinary output, not a refusal or an exit code.
- `lanq.yml` refuses YAML anchors and aliases (`&name`, `*name`) with their line number, so an alias-bomb file cannot
hang lanq.
### Fixed
- Windows workers denied WMI showed `ram ?`, a silent `load 0.00` and size `unknown`, and a timeout, stop or stale-slot
cleanup could leave the job's process tree running.
- `dotnet` passed `lanq doctor --remote` on a worker with only a .NET runtime, and the job then failed with "No .NET
SDKs were found".
- With `--plan` and `--wait 0`, a job no longer ends `NoCapacity` when a sibling frees the slot just after the job saw
it taken; it looks again first (also for jobs with shards).
- When several plan jobs fail, the plan exits with the first failed job's own exit code in `lanq.yml` order, whatever
order they were launched in.
- When a Windows job times out, its process tree is walked before the job object is ended, so a grandchild started
before the job object took hold is stopped too.
Full changelog: https://github.com/jangolath/lanqueue/blob/main/CHANGELOG.md