vq 0.26.9 “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

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

vq is part of a set: vibe-qc computes, vibe-view renders the results, and vq decides where the work runs. Each is usable without the others.