Guards for AI agents working on your own machine.
An AI agent on your machine runs shell commands, reads and writes files and
fetches pages. Most of that is fine. Some of it is not: a rm -rf one folder
too high, a cat of your SSH key, a fetch of the cloud metadata service.
Something has to say which is which before it happens, and fast enough that
the agent does not stall on every step.
That is what a guard does. You hand it what the agent is about to do and the places the agent works in, and it answers in microseconds: safe to do without asking, or risky, with the reason in a few plain words a permission prompt can show.
| The agent is about to run | The answer |
|---|---|
cargo build && rm -rf target, inside the project |
safe |
rm -rf ~ |
risky: delete, "deletes your home directory" |
cat ~/.ssh/id_ed25519 |
risky: read_secret, "reads your SSH keys" |
./script.sh |
cannot be told, so it is not called safe |
The guards are built for agents that run with small local models, so they ask nothing of a model and nothing of the network. A guard is a plain function. It runs offline, reads no file and no environment variable, and gives the same answer for the same input on every machine.
- Not a sandbox. A guard does not run the command and does not stop it. Whatever you let through runs with all your rights.
- Not a decision. A guard reports. Whether to ask, refuse or allow is your policy, and you can choose differently for each rule.
- Not a proof. Safe means no rule found anything. What a guard cannot read at all, such as a program known only when the line runs or a line too deep to parse, comes back risky, never safe.
milo-guards is a Rust library on crates.io. The one crate a caller depends on
is milo-guards; the guards are crates of their own behind it
(milo-guards-shell, -file, -url, -secrets, with -core and the
-code reader), published together at one version.
[dependencies]
milo-guards = "0.1"Each guard sits behind a cargo feature. shell, file, url and code are
on by default; secrets is opt in, because most callers want the others and
not a table of credential patterns in their binary.
# Everything, the secrets guard included
milo-guards = { version = "0.1", features = ["secrets"] }
# Only the shell guard
milo-guards = { version = "0.1", default-features = false, features = ["shell"] }To depend on a commit instead, the git form works too, pinned to a release
tag (v0.1.2 is the latest):
milo-guards = { git = "https://github.com/camiloazula/milo-guards", tag = "v0.1.2" }It needs Rust 1.99 or newer. If your program also links tree-sitter, it has to be on the 0.26 runtime: tree-sitter allows one version per lockfile, and the guards are on 0.26.
The crates follow semver at 0.x: a release that changes what a caller
compiles against is a minor bump (0.1 to 0.2), and a fix of what a guard
answers is a patch (0.1.0 to 0.1.1). The rule enums are exhaustive on
purpose, so a new rule is a minor bump: it breaks a caller's match at
compile time, where the caller decides what to do with the rule, and a
caller pinned to "0.1" is never handed a rule it has no answer for. A
guard that judges a line differently after a fix is a patch, since the API
is the same, and the change is in the changelog.
A command-line program for callers that are not written in Rust is planned, with npm and Homebrew packages. Until it ships, the library is the way in.
Four guards and a reader. Each guard takes one thing the agent is about to do
and the Paths it works in, and returns an Assessment: Safe, or Risky
with a Finding for each reason.
| Guard | Judges | Risky, for example | Safe, for example | Feature |
|---|---|---|---|---|
| shell | one shell line: POSIX shell, PowerShell or cmd | rm -rf ~ (delete) |
ls src |
shell, on by default |
| file | one read or write of one path through a file API | reading ~/.ssh/id_ed25519 (read_secret) |
writing src/main.rs |
file, on by default |
| url | one URL the agent is about to fetch | http://2130706433/, which is 127.0.0.1 (local_address) |
https://docs.rs/url |
url, on by default |
| secrets | a text, for the credentials and personal data in it | postgres://app:fakePass0word1@db/app (connection_string) |
a commit SHA | secrets, opt in |
The code reader is not a guard. It reads Python and JavaScript (Node, Bun
and Deno) and says what the code is certain to do: the files it deletes,
writes, reads and moves, and the programs it starts. The shell guard uses it
for the code a line hands to an interpreter, so python3 -c "import shutil; shutil.rmtree('/home/me')" is judged as the delete it is, and
python3 -c 'print(1)' is safe. Code the reader does not understand in full is
never taken for harmless.
What sets the guards apart:
- Structure, never text. The shell guard parses the line with tree-sitter and judges the programs, flags, operands and redirects it finds. There is no pattern match on the raw line to slip past.
- Spelling-proof. A path is placed by how it is spelled, with
~,.., Windows drives, shares, short names and any case, without touching the disk. A URL is judged by the host a WHATWG parser reads, so a decimal, octal or IPv6-mapped spelling of a local address is still local. - Two more answers from the shell guard.
effectsays whether a line only reads, changes something or cannot be told, and whether its reads stay in the workspace.explainshows how the line was read, unit by unit, with what each unit found. - Your own files, in your own words. Name the paths your tool keeps for itself, such as its settings or its rules, as protected. A finding about them says "deletes the agent's settings", in the words you gave.
- No secret in a finding. The secrets guard reports a masked target such as
… (14 chars)and the byte ranges of what it found, so you can scrub the text before it goes anywhere. - Stable rules. Every finding carries a rule with a wire name that never
changes once published. The rule enums are exhaustive, so a new rule breaks
your
matchat compile time, where you decide what to do with it; it ships as a minor bump (Versions).
| Guard | Rules, by wire name |
|---|---|
| shell | delete, wipe_disk, overwrite, git_discard, git_remote, git_history, permissions, system_settings, read_secret, elevated, run_downloaded, run_input, stop_system, stop_unknown, send_secret, drop_data, destroy_resources, unknown, unreadable |
| file | read_secret, write_outside, write_sensitive, write_protected, network_share, unreadable |
| url | local_address, metadata, credentials, local_file, scheme, unreadable |
| secrets | private_key, cloud_key, api_key, jwt, basic_auth, bearer_token, connection_string, url_credentials, generic_secret, credit_card, government_id, email, phone, public_ip |
What each rule covers is documented on the guard's Rule enum, and in depth
on its design page: shell, file,
url and secrets.
Every guard keeps five promises, and the test suite enforces them. How is in the architecture page.
- No I/O and no environment. A guard never reads a file, a variable, the clock or the network, and never starts a process.
- Deterministic. The same input gives the same answer, on every run and on every machine.
- No policy. A guard says what it found. It has no modes and never decides for you.
- What cannot be read is risky. A guard never answers safe because it gave up.
- Never panics. Whatever the input, a guard returns. It runs on every action an agent takes, and a panic there would fail the agent's turn.
Build the Paths once: the agent's working directory, the user's home and the
folders the agent may change. Then ask a guard about each thing the agent is
about to do. This example is compiled and run with the tests, so it is as
current as the code.
use milo_guards::file::{judge, Access};
use milo_guards::shell::{classify, effect, Effect, Reach, Shell};
use milo_guards::{Paths, Protected};
// Where the agent works, and what your tool keeps for itself.
let paths = Paths::new("/home/me/work/app", "/home/me", ["/home/me/work/app"])
.with_protected([Protected::folder("/home/me/.agent", "the agent's settings")]);
// Inside the workspace, building and cleaning are the agent's own business.
assert!(classify("cargo build && rm -rf target", Shell::Posix, &paths).is_safe());
// Beyond it, the answer says what the line would do.
let verdict = classify("rm -rf ~", Shell::Posix, &paths);
for finding in verdict.findings() {
// Ask, refuse or let it through: that part is yours.
println!("{}: {}", finding.rule.name(), finding.reason);
}
assert_eq!(verdict.findings()[0].rule.name(), "delete");
assert_eq!(verdict.findings()[0].reason, "deletes your home directory");
// Your own files get your own words.
let verdict = classify("rm ~/.agent/config.yaml", Shell::Posix, &paths);
assert_eq!(verdict.findings()[0].reason, "deletes the agent's settings");
// Whether a line only reads, and whether those reads stay in the workspace.
assert_eq!(effect("git status", Shell::Posix, &paths), Effect::ReadsOnly(Reach::Workspace));
assert_eq!(effect("cat ~/.ssh/id_ed25519", Shell::Posix, &paths), Effect::ReadsOnly(Reach::Beyond));
assert_eq!(effect("./script.sh", Shell::Posix, &paths), Effect::Unknown);
// One read or write through a file API, judged against the same places.
assert!(judge(Access::Write, "src/main.rs", &paths).is_safe());
let verdict = judge(Access::Read, "~/.ssh/id_ed25519", &paths);
assert_eq!(verdict.findings()[0].reason, "reads your SSH keys");The other guards read the same way. url::judge(url, &paths) judges a URL,
secrets::find(text) reads a text and secrets::find_spans(text) gives the
byte ranges to scrub, and code::read and code::understand read a snippet of
Python or JavaScript. Every example in the crate's documentation is a test too;
cargo doc --open shows them all, one per guard.
A finding has four fields: rule, the enum value with its wire name; reason,
the words to show; target, what the finding is about, when there is one; and
instead, what to do instead, where there is a real way out (git stash before
a git reset --hard). A finding about a secret never holds the secret.
If a guard calls a harmless line risky, that is a bug: open an issue. If it calls a line safe that deletes, overwrites or sends something beyond the workspace, or runs something the line does not show, report it privately as SECURITY.md describes.
To go further: the design pages in docs/design say how each guard reads its input, GUIDELINES.md holds the rules the code follows, and CONTRIBUTING.md says how to build, test and submit a change.
Copyright (c) 2026 Camilo Azula. Licensed under either of the Apache License, Version 2.0 or the MIT license, at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.