Running a host

Audience: the machine is yours. You install the daemon, decide what a job may consume, and are the one who finds out when a host stops answering.

Most of this corpus is written for you. It is the largest of the three audiences and the least forgiving, because the failure modes are operational rather than conceptual.

Start here

The daemon is a supervised, long-running process that owns durable on-disk state. Three consequences shape everything below:

It is not stateless. State outlives any single process, and a daemon inherits the state the previous one left. Version compatibility is the contract between a daemon and state written by an older one; a rolling fleet update depends on it.

It refuses to run as root. By design, and the lifecycle lock binds a checkout to its owning uid. Multi-user deployment is a separate, deliberate mode, not what you get by using sudo.

Update and reinstall are different operations. vq self-update / vq admin update own service restart together with git and venv rollback. scripts/reinstall.sh owns neither and must not run while a daemon is up.

Setting a host up

• Clone, download, and install — the standalone repository, GitHub mirror, and installation profiles.

• Host records — what to know about a machine before you point a queue at it, and why the filled-in inventory for this project’s own fleet is deliberately not in this repository.

• Reaching the queue from the internet — SSH hardening, key-only auth, router forwarding. vq needs no changes: make SSH reachable and hardened, and vq is too.

• Daemon lifecycle — supervision, provenance, restart and recovery rules.

• The web dashboard — read-only by default, and not meant to face the internet.

Keeping it honest

• cgroup setup — real containment for CPU and memory, rather than a heuristic.

• Draining a host — stop dispatch without killing running work, which is what you want before maintenance.

• Throttling — soft CPU-priority adjustment for a job that is winning too hard.

• Automatic cleanup — terminal jobs do not archive themselves unless you say so.

More than one machine, more than one user

• The fleet console — cross-host view, accounts and audited write actions.

• Public fleet snapshot deployment — writer timer, isolated static serving, freshness monitoring and rollback.

• Multi-user deployment — privileged shared installation under /opt/vq, ownership checks, admin group.

• Retiring a multi-user deployment.

• One directory layout for every host — homes sorted by lifecycle, the reviewed-plan migration tool, and the steps that need the maintainer first.

• Scheduler runtime deployment — hosts where PBS or SLURM, not a vq daemon, owns dispatch.

• Portable runtime bundles — package once, verify and relocate to compatible prefixes without target builds.

• Runtime benchmark campaigns — plan a generic-versus-optimized comparison and analyze its runs: paired ratios, intervals, explicit exclusions and break-even.

• Explainable placement plans — where a job would run across daemon hosts and scheduler lanes by predicted completion time, with every rejection and score component shown.

• Runtime slots — verified, immutable generations for a program, and the reviewed vq admin migrate-runtime transaction that moves a registration onto them. Accepted on one direct host so far.

• Repair recorded state paths — plan and preserve terminal records after an explicitly mapped state-root move.

• Operations — the long-form operational reference.

• Driving vq from a script — what a chain of vq admin update calls may rely on: match on outcome and its exit code, never on message text.

When a host stops answering

Host recovery channels defines the tiered contract every fleet host must satisfy before it joins, precisely because the moment you need a second way in is the moment you cannot set one up.

In the source tree, not on this site

These pages describe the product as it is but are not published here. Read them on the source tree.

• state_file_audit.md — where every file vq reads or writes lives, and which setting wins. Swept at v0.25.0; its opening note says what has been added since.

• fleet_update_runbook.md and fleet_update_prompt.md — what an operator’s own runbook must preserve when updating a fleet host, and what to hand a maintenance agent.