Install
Vacant is the Python package vacant-network. After installing it, use vacant on to pick, from a menu, an AI assistant already on your computer and launch it under mediation, without touching your persistent settings.
#Requirements
| Python | 3.11 or later |
| Operating system | macOS, Linux (the sandbox cannot be built on Windows) |
| Model channel | Any OpenAI-compatible endpoint: LM Studio, Ollama, vLLM, or a cloud API |
| AI assistant | A command-line agent (Codex, OpenCode, Claude Code, pi…), or an OpenAI-compatible agent you wire up yourself |
#Three ways to connect, with different levels of enforcement
This is the single most important thing to know before installing. Vacant's guarantee that "every call goes through me" has a scope that depends on how it is connected.
| Form | Enforcement | Notes |
|---|---|---|
| Library / MCP tool | Voluntary | The agent registers Vacant's MCP server in its own settings and can call tools such as delegate. If the agent doesn't call them, Vacant has no way to step in. |
| Controller | Only for child processes it launches itself | It delegates, runs acceptance, then launches the downstream agent. The guarantee covers only processes launched through this controller; the same operating-system user can bypass it and run the agent directly. |
| Execution harness that owns the loop | Fully enforced | Generation, acceptance and shipping are all controlled by it. The runner of the gain experiments belongs to this category. |
A test in 2026-07 preserved a cautionary example: the Hermes agent was missing one environment variable and quietly connected straight to an external service. Apart from requests_seen being zero, every field in that cell looked like a legitimate refused delivery. So the requests_seen field on the receipt is the only evidence that can prove mediation really happened — "I set the environment variable" is not evidence.
#Install
git clone https://github.com/cosmopig/Vacant.git
cd Vacant
pip install -e .
# or
pip install git+https://github.com/cosmopig/Vacant.git#Two ways to launch, with different evidence levels
#vacant on (doesn't change your settings; recommended)
vacant onPick, from a menu, a command-line agent that actually exists on your computer, and launch it under mediation. vacant on writes the base URL into this run's own temporary settings directory and does not touch your persistent settings files. The menu marks how far each agent's channel has been verified, for example "channel verified" or "channel not measured; check requests_seen after the run."
#vacant install (changes persistent settings)
Changes the agent's persistent settings. The two have different evidence levels and cannot vouch for each other — a receipt produced with install cannot be used to prove that the on channel works.
#Where the delivery point is
vacant run, added on 2026-09-18, is built on one observation: if all you want is to stop a delivery, the trigger point is not in the network protocol but at the moment the agent process exits. This signal is completely reliable, needs no protocol knowledge, costs no tokens, and holds across all frameworks.
Its flow:
- Start a local proxy server and, following a list, set the agent's base URL environment variables; remove the real upstream address and key from the agent's environment, keeping them only in the proxy server process.
- Record the workspace's tree hash.
- Launch the agent and wait for it to exit; after it exits, terminate the whole process group, so that grandchild processes cannot write after the freeze.
- Run the visible acceptance tests on the frozen workspace snapshot, and measure the tree hash again; if they differ, mark it as an infrastructure failure.
- Sign every attempt and every cell's verdict, and reflect the verdict in the exit code.
| Exit code | Meaning |
|---|---|
0 | Delivered |
20 | Refused delivery |
22 | Infrastructure failure (tree hash mismatch) |
#Receipt levels
A receipt states clearly how much it has proven. The level is decided by probe results, not by the inference "we installed it."
| Level | Condition | What the receipt can say |
|---|---|---|
| A | Fence in place, framework-hook probe triggered, 0 unexplained calls | Every model call went through Vacant, and each one matches a tool event |
| B | Fence in place, no hook | Every byte that left is recorded, but it can't tell which call was made by the model |
| B′ | The model channel is not (or not fully) in Vacant's view, but the tool layer is recorded | It can only account for tool-layer events |
| C | Neither | Refuses to issue a receipt |
The first A-level receipt for a real agent was signed on 2026-09-20 (pi 0.85.1 running on a real model, 0 unexplained calls). Every coverage field is three-state (true, false, not measured) — a value that was not measured must not be written as zero or false.
#Next
- Actually run it once: Quickstart
- What the gate does behind the scenes: The executable acceptance layer
- Re-run our experiments yourself: How to reproduce
