LanQueue 0.2.0
See the version list below for details.
dotnet tool install --global LanQueue --version 0.2.0
dotnet new tool-manifest
dotnet tool install --local LanQueue --version 0.2.0
#tool dotnet:?package=LanQueue&version=0.2.0
nuke :add-package LanQueue --version 0.2.0
LanQueue
Put the spare machines on your own network to work, without giving up your desk.
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. It checks which ones are awake and not busy, picks the least loaded machine 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
and a shell), and it sends nothing anywhere except to the hosts you list. There is no telemetry.
Why this exists
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 records wall-clock time per job in a local log. There are no published measurements yet, and this README
makes no speed-up claim.
Install
Requires the .NET 10 SDK or runtime on the machine you run lanq from, and git and ssh/scp on the PATH.
Remote machines need git and an SSH server (Linux: sh; Windows: OpenSSH Server with PowerShell 5.1+).
dotnet tool install --global LanQueue # works once the first release is published to NuGet
# from source, from a clone:
dotnet pack src/LanQueue -c Release -o ./nupkg
dotnet tool install --global --add-source ./nupkg LanQueue
Quick start
Before your first job, each worker needs an SSH server, git 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.
Copy
machines.example.ymlto a private location (for example~/.config/lanq/machines.yml, or%APPDATA%\lanq\machines.ymlon Windows) and edit it. A config in the current directory is never picked up implicitly; pass--config FILEor setLANQ_CONFIG.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 the fleet:
$ lanq health build-01 OK load 0.12 disk free 180.4 GB slots 0/2 build-02 HOLD load 0.05 disk free 90.1 GB slots 0/1 (outside allowed hours)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.lanq statssums wall-clock time from your local log.
Exit codes: the job's own code; 2 rejected by policy or bad arguments; 70 infrastructure error (SSH, git);
75 no eligible machine.
How it works
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 wall-clock time 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; a hit refuses the job before anything is sent. |
| 4-5 | Machines that are unreachable, loaded, outside their hours, low on disk or missing a capability are skipped. |
| 6 | max_jobs is enforced with an atomic slot file per machine. |
| 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 steps in words
- 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. - The worktree, ref, bundle and slot are removed, even if the job failed. Wall-clock time is appended to
<state>/jobs.jsonl. Any.lanq/folder in the repository is excluded from the snapshot.
Keeping your keys safe
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).
Two ways to use it
As a developer, directly
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 stats # wall-clock time per machine
You own machines.yml and the allowlists. Edit them yourself; nothing else should.
With a coding agent such as Claude Code (scripts-first)
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 40
The agent keeps the exit code and a short tail, and opens more of the log file only when the tail is not
enough. The log lives in the temp folder, not in your repository; lanq also keeps full per-job logs in its own state
folder ($LANQ_HOME, else a per-user folder). (A .lanq/ folder in the repository is excluded from the snapshot.)
Ready-to-copy assets live in docs/agents/:
CLAUDE.md-snippet.md: rules to paste into your project'sCLAUDE.md.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.
Configuration reference
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/lanq # Linux: absolute path. Windows: a drive path such as D:/lanq. Forward slashes, no spaces, no ".."
capabilities: [dotnet] # tags matched by --needs (all must be present)
max_jobs: 2 # concurrent jobs via slot files
allowed_hours: "22:00-07:00" # optional; local time of the machine running lanq; may wrap midnight
Unknown keys are an error (so a password: field is refused rather than ignored). 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); it defaults to a per-user folder outside any repository.
Security model
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. 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). This is a safety net, not a guarantee: it does not scan committed history or binary files, and it cannot recognise every secret format. - 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 per job, removed afterwards. Gitignored files are never shipped.
- No telemetry, no network access except the SSH hosts you configure.
See SECURITY.md for what this does not protect against.
Limitations (v0.1)
- The secret scan is pattern-based and best effort; it does not scan already-committed history or file contents of binary 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 (if the network is down, the job may keep running until it ends on its own), and a job that deliberately detaches into a new session or process group can escape it. - Windows remote commands are passed as an encoded command line limited to roughly 8000 characters; very long argument lists are refused with a clear message.
- The full HEAD history is bundled on every run (no incremental transfer yet).
- A crashed orchestrator can leave a slot file behind; delete
locks/slot-N(and any stalelocks/job-*.pid) under the machine'swork_root. - No persistent queue:
--waitpolls every 15 seconds. Windows arguments containing embedded double quotes can be mangled by PowerShell 5.1 native-command argument passing. allowed_hoursuses the clock of the machine runninglanq. 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.
Compared with interactive agent-fleet apps
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.)
Contributing and licence
See CONTRIBUTING.md. MIT licensed, see LICENSE.
| 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 |