vq 0.26.42 “Raymond’s Bazaar”¶

vq is a cross-machine job queue. It takes a command, runs it on the machine you point it at — your laptop, a server over SSH, or a cluster behind PBS or SLURM — and tracks it until you fetch the results back. It was built to run vibe-qc calculations and it does not care whether that is what you run.

vq submit compute -- python optimise.py
vq queue
vq fetch <jobid> -o results/

vq needs Python 3.12 or newer, and installs nothing on the remote host but itself. Its entire transport is SSH: if you can ssh to a machine, vq can queue work on it.

Get vq¶

Start with clone, download, and install for the split repository layout, source archives, and the GitHub mirror.

Three ways to read this¶

This documentation serves three readers who want almost nothing in common. Start in the right place.

I want to run jobs

Submit work, watch it, get the results back. Dependencies, arrays, retries, wall-time limits, and what to do when a job will not start.

Running jobs

I run the machines

Install and supervise the daemon, register engines, expose a host safely, cap what a job may consume, deploy for several users, and recover a host that has stopped answering.

Running a host

I am an agent

The machine-readable contract: stable JSON shapes, exit codes, the states a job moves through, and the invariants you may rely on between versions.

The agent contract

This manual follows the current source with package version 0.26.42; source updates may precede deployment on a particular host.

Available workflows¶

The current source includes direct and SSH submission, PBS/Slurm driver queues, an opt-in durable fleet broker, immutable runtime slots, campaigns, resource-estimate receipts and placement explanations. The broker holds work until a configured daemon host has capacity; PBS/Slurm targets continue through their scheduler drivers. See broker operation, runtime slots, campaigns, resource estimates and placement. Availability on a particular machine depends on its installed version and operator configuration. A source feature does not enable itself on a host.

What vq guarantees¶

The three that matter most, because they are what the rest is built on:

A job’s state is durable. Every transition is written to disk before it is reported. A daemon restart, a reboot, or an SSH drop does not lose a job or silently change its outcome; an interrupted job says it was interrupted.

Dispatch is capped, and the caps compose. A job runs only when the CPU, memory and concurrency budgets all allow it. A per-submitter quota can tighten a host’s global cap and can never loosen it.

vq stays out of the transport. Hostnames, ports and keys live in ~/.ssh/config, not in vq’s configuration. Nothing in vq changes when a host moves onto the internet.

Where to find the rest¶

Changelog — CHANGELOG.md
Reporting a bug — CONTRIBUTING.md; for anything security-relevant, SECURITY.md rather than a public issue
Public source — GitHub mirror. Private GitLab access details come from the maintainers.
Cutting a release — the release process, and version compatibility for what a vq version means to a fleet
What is next — the roadmap: what is planned, and what is released but not yet proven on a host
History and design records — kept in the source tree, not published here. Each says in its first paragraph what it is. Four are history: roadmap_history.md (v0.1 to v0.9), v0_7_1_lamports_clock_design.md, pbs_dispatcher_backend_design.md and wall_time_design.md. Two record designs now implemented in increments, including remaining limits: design_immutable_venv_runtimes.md and design_broker.md. Their current user-facing instructions are in runtime slots and broker operation. Where any of them disagrees with vq <command> --help, the help is right.

The family workflow is sketch → submit → calculate → analyze: vibe-sketch prepares structures and inputs, vq submits and tracks work, vibe-qc computes, and vibe-view analyzes the results. Each product has its own installation; local calculations can skip queue submission.