leasehold

Run several coding agents on one Linux machine without it grinding to a halt.

Four agents each decide to run cargo test or pytest -n auto at the same moment. Each one sizes itself for the whole machine, so together they ask for four machines' worth of CPU and memory: memory fills and the machine swaps, your editor and git status stutter, and sometimes the OOM killer takes one of the jobs.

leasehold sits between the agents and the machine. A heavy command takes a lease on a share of the machine before it starts: it waits its turn when the machine is full, runs sized to the share it was given (CARGO_BUILD_JOBS, PYTEST_XDIST_AUTO_NUM_WORKERS, a make jobserver), and, where systemd allows it, runs in a cgroup weighted to that share. When the agent's session ends, whatever it left running is stopped.

What it changes, measured

Eight simulated agents start test runs and memory-hungry builds at random on an 8-CPU, 16 GiB machine (method and full tables):

The machine stays usable and nothing is lost, at a price: the same work took up to 1.5 times as long, because heavy jobs wait their turn instead of overlapping. One machine and one run per condition so far; the memory results vary from run to run.

Since 0.4, a config setup writes for a machine of 4 to 7 slots runs two heavy jobs at once (weight 3 each on 6 slots) instead of one at weight 4. In a pre-registered gate of 8 rounds on the same machine, that cut the time to finish the same work by 14% and each job's mean time by 20%, with git status and wakeup latency within the gate's margins (the verdict).

Start

uv tool install leasehold
leasehold setup                 # a config sized for this machine, your own daemon, the PATH shims
leasehold run -- claude         # or codex, gemini, aider, any agent
leasehold top                   # who holds the machine, who waits and why

setup says what it did at each step, is safe to repeat, and leasehold setup --remove undoes it. It needs no root. Try it without installing anything first: uvx leasehold demo runs a made-up busy machine in top.

Inside leasehold run, the agent's heavy commands (pytest, cargo, make, npm test, go test and the like; leasehold commands lists the rules) go through small PATH shims that take a lease first. Light commands run as they are. A heavy command waits in line, keeping its place, for up to five minutes; one still waiting then is refused with the reason, which the agent reads:

leasehold: machine busy for 300s: cargo test (session claude_3f9a1c) holds 8 slots, 2 other
leases hold 4; pool work holds 12 of 12; this needs 4; gave up its place in line (#1). The
command did not run. Do lighter work first, then run it again.

In Claude Code, the plugin does the same through a hook, without the shims:

/plugin marketplace add chalkworth/leasehold
/plugin install leasehold@leasehold

What it promises

leasehold decides when a command starts and how much of the machine it may use while it runs. It never decides what runs, and it only touches the processes it started itself.

• A heavy command takes a lease on slots (one slot per CPU, a few kept back for you) before it starts and gives it back when it ends. A holder that crashes gives it back within seconds. Commands that run the job count they are given stay off the kept CPUs; one that ignores it can still fill every CPU unless [contain] hard_cpu = true caps it (leasehold doctor warns while it is off). Turns go round fairly by user, then by agent session, so one busy agent cannot starve the others.
• The lease's size reaches the command as the job-count variables that cargo, make, ninja, CMake, pytest-xdist, Go and others read, and optionally as a GNU make jobserver shared by the whole build tree.
• Where there is a systemd user manager (most desktop and server distributions), each command runs in a user scope with CPUWeight in proportion to its lease and, when a rule says so, a MemoryHigh. leasehold doctor says whether this machine is enforced (systemd) or advisory, and why. Advisory means the lease and sizing still apply, but a command that ignores its job count is not held back.
• A command can declare the memory it will use (hold --memory, or its rule's memory), and declared sizes are counted against a budget: the machine's memory less a share kept for you. A command that declares nothing counts a share in proportion to its weight, which never holds back more than the slots already do, so the budget only binds declared and standing memory. When memory pressure rises, nothing new starts until it eases, and then only within the memory measured free. Other programs' memory is not counted: the guard reacts to it once it shows as pressure (measured).
• leasehold run puts the agent's session in a slice of its own and stops what it leaves behind (a stray test server, a hung build) when the agent exits.

How it compares

The first question is why not a systemd slice, or nice; the first row answers it.

Also works for

The same daemon serves a machine several people or CI runners share: one system daemon under systemd, --kind external leases for self-hosted runner jobs, fair turns across Unix users, spare capacity lent out and revoked when work arrives, and a webhook, Prometheus metrics and a browser view. docs/reference.md has the system setup, every config key, the command line, the HTTP API and the exit codes; examples/ has a runnable example of each.

A Python tool can take leases itself, without running hold:

import leasehold

with leasehold.lease(4, kind="external", timeout=600) as lease:
    lease.run(["make"], jobserver=True)  # make's jobs follow the slots granted

The reference's From Python section covers the errors, cancelling a wait, running commands under a lease, and a fake daemon for tests.

What it is not

• It is not a scheduler: it never runs, places or retries your jobs.
• It is not a sandbox. Containment shares CPU by weight and throttles memory softly; it does not stop a command from using an idle machine, and it cannot prevent every out-of-memory kill. Without a systemd user manager, it is advisory only.
• It runs on one machine, Linux only. It reads /proc/pressure and uses cgroup v2.

Stability

leasehold is alpha and before 1.0. The command line, exit codes, config file, HTTP API with its status schema, the names leasehold exports (leasehold.__all__: lease(), Lease, Command and their errors), and the library modules model, admission, ledger, quota and client are its interface; a minor release may change them, and CHANGELOG.md says how. The ledger file is not an interface.

Licence

Apache-2.0. See LICENSE. SECURITY.md says what leasehold trusts and how to report a problem; CONTRIBUTING.md how to work on it.