LanQueue 0.6.0
See the version list below for details.
dotnet tool install --global LanQueue --version 0.6.0
dotnet new tool-manifest
dotnet tool install --local LanQueue --version 0.6.0
#tool dotnet:?package=LanQueue&version=0.6.0
nuke :add-package LanQueue --version 0.6.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. lanq health --json and lanq run --json print machine-readable results for scripts and coding agents.
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.
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
"&|<>^%, whichcmd.exeshims would re-parse). - 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 |
### Agents and scripts
- `nextSteps` in every `--json` object: each run, dry run, `lanq health` row, init, wake, `makeready --all` and `--add`
object and every error object. Each step is `{action, reason, command?, argv?, safeToRunUnattended}`. `action` is
one of `proceed`, `retry`, `wait`, `fix_code`, `fix_command`, `ask_developer`, `run_doctor`, `run_health`, `none`
(treat an unknown one as `ask_developer`). `argv` is authoritative; `command` is the same as one line for bash and
PowerShell when that is safe. A suggestion never does more than the command it follows and is never `unlock`,
`init`, `wake`, `--force`, `--yes` or `--add`. The single `lanq makeready <machine> --json` report is unchanged and
has none.
- `retryable` and `excluded` on `NoCapacity` (exit 75): `retryable` is false when no machine can ever take the job as
configured; `excluded` lists each machine with a `reason` code (`missing_capability`, `busy`, ...), `why` and
`permanent`.
- `lanq run --dry-run`: what `lanq run` would do now (the same checks, snapshot scan, probe and choice: the machine,
every excluded machine and why, `--shards` N and placement, the machine it would wake) without claiming a slot,
sending, logging or waking anything. Exit 0 would start, 75 no machine now, 2 refused. `--json` prints one object
with status `WouldRun`.
- `lanq health --needs a,b [--mem N]`: judges every machine for such a job as `lanq run` does
(`-> eligible (2 slots)` or `-> not eligible: lacks gpu ...`); JSON rows add `eligible`, `why`, `reason`,
`permanent` and `jobSlots`. Exit 0 when a machine is eligible, 75 when none is.
- `logPath` in every `lanq run --json` object (the job's local log; null when no job started) and `--log-tail N`
(1 to 200, `--json` only) for its last N lines as `logTail`. Agents no longer need to redirect stderr to a file.
- A run cancelled with Ctrl+C after its job started now reports that job's `logPath`.
### Adding a machine
Every write is local; lanq still never changes a worker.
- `lanq makeready --ssh user@host --os windows|linux --setup` prints the PC's full one-time setup and connects to
nothing: the build user, your public key in its `authorized_keys` (Windows: every grant by SID), the work folder
(`C:/lq`, `/srv/lq`), firewall scoping, the host key fingerprint check, the first connection, then password logins
off. Only `.pub` files are read.
- `lanq makeready --ssh user@host --os X --add --name NAME [--yes]` scans the PC and adds it to `machines.yml` only when
it is READY: as text after the last machine, every other byte kept, checked before an atomic replace, never through
a link. It asks first (`--yes` without a terminal and with `--json`), then probes the new machine once.
- `--key-env VAR` with `lanq makeready --ssh`: scan with that key and write `key_env: VAR` into the entry.
- `lanq makeready --ssh` that fails because the key was refused or the host key is unknown now suggests `--setup`.
- `lanq init`'s next steps now show `--setup`, then `--add --name`, then deleting `example-01`.
### Behaviour changes
- Fail fast on exit 75: when no machine can ever take the job (none has every `--needs` capability, `--mem` above
every machine's RAM, git or tar missing, ...), `lanq run` ends at once with `retryable: false` instead of waiting
out `--wait`, and never wakes a machine. The message starts `No eligible machine, and no machine can ever take this
job as configured (waiting will not help).` The exit code is still 75.
- The `NoCapacity` message gives the reason waiting cannot cure first: a machine that is down and lacks a capability
says `lacks gpu (...)` instead of its ssh error.
- `Next: ...` lines on stderr for people (`[lanq] Next: ...` in `lanq run`), before the `[lanq] log: <path>` line and
the final `[lanq] <Status>: ...` line, which stays last. stdout is unchanged in text mode.
- `lanq health --json` rows gain `nextSteps`; nothing else in a plain `health` row changes.
- `lanq init`'s starter `machines.yml` uses `work_root: /srv/lq` (and `C:/lq` in its Windows example), the same
folder `makeready` and `--setup` suggest.
### Releases
- Release notes from CHANGELOG.md now appear on nuget.org and on the GitHub release.
### Docs
- New: https://github.com/jangolath/lanqueue/blob/main/docs/JSON.md (the `--json` contract: every field, status,
reason code and the `nextSteps` rules), a tool-agnostic https://github.com/jangolath/lanqueue/blob/main/AGENTS.md,
https://github.com/jangolath/lanqueue/blob/main/llms.txt and
https://github.com/jangolath/lanqueue/blob/main/docs/AGENTS-GUIDE.md with snippets for agent instruction files.
- Agent docs use `--log-tail` and `logPath`, a dry run before heavy work, `retryable`, and only `nextSteps` that are
safe unattended.
- https://github.com/jangolath/lanqueue/blob/main/docs/TEAM-QUICKSTART.md follows `--setup` and `--add`, uses
`C:\lq` and `/srv/lq`, grants by SID, cuts the work folder's inherited ACL, turns off keyboard-interactive logins on
Linux and explains when a ufw LAN rule does nothing.
Full changelog: https://github.com/jangolath/lanqueue/blob/main/CHANGELOG.md