What is jobwarden?

jobwarden is a daemon that distributes job server task tokens to multiple users on a Linux system. This allows a two different users to run massively parallel build processes without overtasking the system. It is Linux-only.

How does it work?

jobwarden listens on a unix domain socket (default @jobwarden.sock, an abstract socket). A process connecting to the server can expose its connection to any make-compatible jobserver compatible process using MAKEFLAGS. jobwarden keeps track of users actively requesting tokens, and tries to distribute tokens fairly between the users/tasks.

The socket can be overridden by setting JOBWARDEN_SOCK in the environment. A leading @ selects the abstract namespace; anything else is a filesystem path. The daemon and the jr client must agree on it.

How do I use it?

Run any jobserver-aware command through the jr wrapper:

jr make

jr connects to the daemon, injects the jobserver descriptors into MAKEFLAGS, and execs the command. The command and any child processes share the daemon's token pool as they would a normal make jobserver.

The jobwarden daemon can run as any user, and required very limited privileges (only the ability to listen on the socket...)

From your own build system

jr is a thin wrapper around the jobwarden library, which other Python build systems can consume directly. Call connect_and_inject() once at startup; this process and its children then act as jobserver clients:

import jobwarden

sock = jobwarden.connect_and_inject()  # keep `sock` alive for the connection
# ... now spawn make/ninja/etc.; they inherit the jobserver via MAKEFLAGS.

in_jobserver_context() is run as a part of connect_and_inject() ; that behavior can be overridden by doing connect_and_inject(check_env=False)

Python version

jobwarden is likely to run on any Linux box with Python>=3.6+. No third-party packages are required.

Running tests

I (and the CI) run the tests with pytest:

uv run --with pytest python3 -m pytest

The suite is stdlib unittest, so python3 -m unittest test_jobwarden also works without any extra tooling.

How do I install it?

Only .deb is supported as an integrated install for now. Patches accepted for additional distro support.

With pip

pip install .

This installs the jobwarden library, the jr client, and the jobwardend daemon. Note that pip does not install the systemd unit; use the .deb for a managed service.

I want to build a .deb

./package.sh builds a .deb using dpkg-deb

./package.sh

The version defaults to using git describe to guess version; override with -v and -r to set version/revision. The package ships the service enabled.

Then run:

sudo apt install ./jobwarden-*.deb

The service is enabled on install and starts on boot. To start it immediately:

sudo systemctl start jobwarden.service