Architecture
How Warden actually works
Six stages. The interesting ones are the last three, because that is where every other tool stops.
It reads the machine
Fourteen collectors sample continuously, each on its own schedule: wireless every two seconds, drive health every minute. Every reading carries the exact command that produced it, how long that took, and how much the collector trusts it. Nothing is inferred at this stage and nothing is judged.
Readings become symptoms
Plain rules, no AI. A condition has to hold across consecutive samples before it counts, so a wireless blip is not an incident. When one fault causes several, the root cause suppresses the rest, because otherwise you get four alarms for one problem.
A local model explains it
The model receives the symptom, the readings that support it, and a short list of permitted actions. It writes the explanation and picks one action. It runs on your processor, so this works with the network down. That matters, because the network being down is one of the things Warden fixes.
The guardrail checks the answer
The chosen action must be permitted for that specific symptom, so a full disk cannot be answered by restarting the wireless adapter. Parameters are checked against reality: it cannot name a network you have never joined. Anything it refuses is shown to you rather than hidden.
You decide
The card shows the exact command, what it will do, why this action, and the test that will decide whether it worked. Nothing happens until you choose, and there is no timer. If the problem resolves itself while it waits, the incident closes having run nothing.
It proves the fix
Warden re-reads the machine and evaluates the test you already approved. Three answers, not two: it worked, it did not, or it could not tell. If it did not work, the incident escalates: the failed action is excluded and the next proposal has to be something else.
Why the AI cannot run arbitrary commands
This is the question worth being precise about, because 'an AI that fixes your computer' should worry you.
The model on your machine never writes a command. It receives a problem and a list of action ids, and all it can output is a choice from that list plus some parameters. Every command is hand-written, sits in the source, and can be read before you install anything.
The cloud model, which is off until you turn it on, may write one, because seventeen actions cannot cover every fault a person can describe. That path is deliberately weaker and deliberately labelled: the exact command is on screen before it runs, a refusal list screens it first, and the result is never reported as verified, because no test measured it.
Then four checks stand between a choice and a running process:
- 1
Approval
The execution function cannot be called without a timestamp proving you agreed. There is no default, no override flag, and no code path that supplies one for you. A test asserts this by inspecting the function itself, so a future refactor cannot quietly remove it.
- 2
Known action
The id must name a real entry in the reviewed list.
- 3
The command is rebuilt and compared
The command is generated again, from the template and the parameters, and checked against the one being proposed. If they differ by a character it is refused. Nothing downstream is trusted to hand over a command, not even Warden's own earlier self.
- 4
Permissions
An action needing administrator is refused up front and explained, rather than failing halfway through after you already said yes.
And throughout: commands are passed to Windows as a list of separate arguments, never as a line of text handed to a shell. There is no shell in the process, so there is nothing to inject into.
Verification is the whole point
A troubleshooter that reports success without checking is the thing this exists to replace. Every action declares its success test beforeyou approve, so you are agreeing to the standard as well as the command, and afterwards “it’s fixed” is a measurement you already signed off, not a claim you have to take on faith.
Read it yourself
The source is public. If you only open three files, open these. They carry the design.
warden/contracts/Every type that crosses a boundary. The rule that a 'needs a technician' verdict cannot carry a runnable command is enforced here, by the type system, not by convention.
warden/playbooks/base.pyThe closed list of actions, each with its command template, its safety checks, and its success test.
warden/executor/runner.pyThe only code in Warden that changes anything, and the four gates in front of it.