vq 1.0.2 “Meyer’s Contract”¶

For renamed products, supported legacy commands, and unchanged package/state identities, see the naming compatibility guide.

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 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. Direct remote submission uses SSH. The optional submission gateway also supports HTTPS clients through vq remote, with resumable uploads, logs, cancellation and verified result downloads. Its outbound connector can serve a broker behind a firewall.

Get vq¶

Start with clone, download, and install for the split repository layout, source archives, and the GitHub mirror. To set up a workstation, a server or a PBS/Slurm cluster, follow installing vq on machines and clusters, then work through the tutorials.

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 1.0.2; 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 and HTTPS gateway, immutable runtime slots and portable bundles, 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, portable runtime bundles, gateway and relay, 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-sketcher prepares structures and inputs, vq submits and tracks work, vibe-qc computes, and vibe-viewer analyzes the results. Each product has its own installation; local calculations can skip queue submission. Running vibe-qc calculations and vibe-sketcher and vibe-viewer with the queue show how the pieces connect.