LanQueue 0.10.1

There is a newer version of this package available.
See the version list below for details.
dotnet tool install --global LanQueue --version 0.10.1
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local LanQueue --version 0.10.1
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=LanQueue&version=0.10.1
                    
nuke :add-package LanQueue --version 0.10.1
                    

LanQueue - your spare machines, back to work

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

  1. Write a starter machines.yml with lanq init (or start from the example), list your machines, and make sure key-based SSH login works.
  2. Check your setup and the fleet: lanq doctor --remote, then lanq health
  3. Run a job from inside a git repository: lanq run --needs dotnet,linux -- dotnet test -c Release
  4. 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_hours per 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 run wakes one sleeping machine only when no awake one can take the job (needs --wait, --no-wake turns it off), lanq health --wake wakes sleepers, both only inside allowed_hours with at least min_window_minutes + wait_seconds of 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 PAUSE file (Linux: PAUSE or pause) in the worker's work_root holds 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/ionice on Linux, BelowNormal on Windows); priority: normal turns it off.
  • Machines with little free memory are held (min_free_mem_gb, Linux memory pressure), and lanq run --mem 4 asks for a machine with at least 4 GB available.
  • Per-machine env: (for example NODE_OPTIONS: "--max-old-space-size=2048") and path_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. Since 0.10.0 --on, --size and --min-size narrow every job of a plan (never widen one), --plan-timeout M or plan_timeout: limits the whole plan, and lanq.yml may only lower the fetch limits (fetch_max, fetch_max_files); only your own --fetch-max, --fetch-max-files and --fetch-dir raise them or pick the folder.

Per-job options

  • --env NAME=VALUE sets a variable for one job, for names you list in policy.allowed_env (none by default); a deny table (loader, runtime startup, toolchain, profile, GIT_* and SSH_* variables) wins over that list. Settings only, never secrets.
  • --exclusive takes every slot of the machine, so nothing else runs there; it waits for an idle machine.
  • --baseline reruns a failed job at the base commit (the merge-base with the default branch, or --baseline-ref) and says whether the failure is new or preexisting; 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, since cmd.exe shims would re-parse them).
  • Worker output is untrusted: control, bidi and zero-width characters are shown as ?.
  • --fetch treats 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, *.pem and similar) and the content of .npmrc, .pypirc and .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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
0.12.0 101 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 88 11/10/2026
0.7.0 93 11/10/2026
0.6.0 88 11/10/2026
0.5.1 91 11/9/2026
0.5.0 91 11/9/2026
0.4.0 97 11/9/2026
0.3.1 91 11/9/2026
0.3.0 86 11/8/2026
0.2.0 99 11/8/2026

### Security

- **A private key replaced in place in a text file is found.** The secret scan reads the uncommitted diff, which
 shows only changed lines: a key whose body changed while its BEGIN line stayed the same never showed its BEGIN line,
 so it was not recognised (files git shows as binary already got this in 0.9.2). Now lanq greps the snapshot's changed
 text files for `-----BEGIN` (`git grep --cached`, only those files), and for each modified or renamed one compares its
 old and new blobs (read by object id, no filters or textconv): an unchanged BEGIN line is scanned again only for a key
 block: a line holding `-----END` (any case) within 8192 lines, every line strictly between them key material (after
 stripping whitespace, runs of the characters `" ' + . & , ; # * > | - /` at the start and `" ' + . & , ; _ \ |` at
 the end (quotes, concatenation, comment and quote markers, a YAML `- `, a `\` continuation), one-letter string
 prefixes and short suffixes (`b"`, `"u8`), `\n` and `\r\n` escapes and XML CR/LF character references: blank, base64 or an armor header such as `Proc-Type: ...`), at least one a base64 line of 16 or more
 characters with a digit, `+` or `/` (lines over 16 KB are never key material), and the new line strictly between BEGIN and END (an edit to the END line alone does not count). Code
 that handles PEM (header and footer constants, adjacent or with parser code between them) never refuses an edit; a
 key in a string concatenation, a comment or a YAML block is still found. A key with no END line, longer than 8192
 lines or written in a form not stripped (see SECURITY.md) is not found when replaced in place, and neither is a
 UTF-16 text file a `diff` attribute forces to text. A changed text file (modified or renamed, with added lines) whose
 path git gives in bytes that are not UTF-8 refuses the job (`scan-incomplete`); other files with such names pass as
 before. The finding reads `private-key-block in uncommitted file
 <path> (key block changed in place)` and never shows the key. A file lanq cannot look up or read refuses the job
 (`scan-incomplete`, with a `git fsck` hint). Such a file is read up to 32 MB per version and 256 MB in all; one over
 that is listed in `scanSkipped` with the new reason `text_over_cap` (the larger version's size) and on stderr, not
 refused. Added files are not read (every line is already in the diff), nor files without a BEGIN line.
- **Colliding file names fail closed.** Two changed paths that git gives in bytes that are not UTF-8 and that decode
 to the same name now refuse the job (`scan-incomplete`), whatever the files are. Before, one of them could hide the
 other from the content scans, the binary scan included.
- **One rename mode for the text scan.** The diff, its file list and the new comparison now always use `-M`,
 whatever `diff.renames` says, so a renamed file is compared with its old version everywhere. The pathspec variables (`GIT_LITERAL_PATHSPECS`,
 `GIT_GLOB_PATHSPECS`, `GIT_NOGLOB_PATHSPECS`, `GIT_ICASE_PATHSPECS`) are removed from lanq's local git calls. The binary scan
 keeps `--no-renames` (a moved binary is read whole).

### Added

- **A Linux worker in Docker on your own PC.** `scripts/docker-linux-worker/` holds a `Dockerfile`, an entrypoint, an
 sshd drop-in and `setup.ps1`. The image is the .NET 10 SDK on Ubuntu 24.04, pinned by digest (runtime 10.0.15), plus
 sshd and git, with key-only login as `lanq`. `setup.ps1`:
 - makes the key, the host key and a private ssh config entry with an `Include` at the top of `~/.ssh/config`;
 - runs the container on `127.0.0.1` only, with `restrict` on the key, 8 GB, 4 CPUs (with a matching cpuset),
   `--cap-drop ALL` plus the six capabilities sshd needs, `--init` and `--restart unless-stopped`;
 - mounts the host key under `/root`, so job code cannot read it;
 - checks the result with `ssh -G` and one login.

 A separate `-Register` step, run by the owner, adds the machine (`size: medium`, `max_jobs: 1`) to `machines.yml`
 and `machines.smoke.yml`. It keeps the change only when `lanq doctor --remote` passes for the machine in every
 file, and restores them all otherwise. See
 docs/WORKERS.md, "A Linux worker in Docker on your own PC", for what it proves and what it does not.
- A test checks that the Docker worker's base image is pinned by digest.

### Behaviour changes

- Edits to sample keys kept in tracked text files are now refused: changing the body of a committed private key (a
 test fixture, a doc sample) under the same BEGIN line refuses the run like a new key. Generate test keys when the
 tests run, or keep such samples out of the files you edit.
- A user whose `diff.renames` is `false` now gets rename-aware file lists and diffs for the scan: a renamed file's
 old name is no longer listed among the changed files (its new name is).

### Documentation

- SECURITY.md and the README now say that the uncommitted diff is scanned with its removed lines too (so removing a
 secret from a tracked file is refused until that removal is committed), and describe the text key-block comparison
 and its limits; `scanSkipped` documents `text_over_cap`.

Full changelog: https://github.com/jangolath/lanqueue/blob/main/CHANGELOG.md