AEGIS: A Pre-Execution Firewall for AI Agent Tool Calls
Runtime policy enforcement for AI agents. Cryptographic audit trail, human-in-the-loop approvals, kill switch. Zero code changes.
At a glance
- What is it?
- Justin0504/Aegis intercepts every tool call an agent makes, classifies it, applies policy, and writes a tamper-evident audit trail. This is what the repository actually ships, and where its documentation stops.
- Who is it for?
- Adopt AEGIS if your agents run tools against production systems and you need a block-before-execute layer plus a reviewable trail, and you are willing to run the gateway and cockpit yourself. Do not adopt it if you need Windows-native support today, or if you cannot accept that the README documents no rollback path for a blocked action.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 10 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap AEGIS targets: tool calls that execute before anyone can object
The README opens with three failure scenarios: an agent running `DROP TABLE users` because a prompt said to clean up old records, an agent exfiltrating 2 GB while answering a request for a report, and an agent running `rm -rf /` after hallucinating a tool name. The claim underneath is structural rather than anecdotal. Agent frameworks let the model choose which tool to call and with which arguments, at machine speed, with no approval step and no undo. AEGIS positions itself as the layer between the agent and its tools: a pre-execution firewall that classifies each call in real time, applies policy, blocks violations, and records what happened.
The audience is narrow and identifiable. It is teams already running agents against real systems, where a tool call can delete data, send mail, or read files it should not. The README's own framing, "one line of code and zero agent changes," tells you the intended integration cost. If your agent only reads from a scratch database, the interception layer adds an operational component for little benefit.
How the gateway, cockpit and policy DSL fit together
The repository is a monorepo. The root package.json declares npm workspaces over `packages/*` and `apps/*`, driven by Turborepo, and requires Node 20 or newer with npm 10 or newer. The runtime pieces visible in docker-compose.yml are two services. The gateway builds from `./docker/gateway.Dockerfile`, listens on port 8080, and stores state at `DB_PATH`, which the compose file sets to `/data/agentguard.db` on a named volume called `gateway-data`. The cockpit builds from `./docker/cockpit.Dockerfile`, listens on port 3000, and receives `GATEWAY_URL` pointing at `http://gateway:8080`. The cockpit waits on the gateway's healthcheck, which polls `http://localhost:8080/health` every 10 seconds with 5 retries and a 15 second start period.
Policy evaluation is where the design gets specific. The README describes the Activity view as showing, for every blocked action, the exact policy that fired and the DSL condition that matched. Named policies appear in the Violations view: `no-privileged-file-access`, `no-arbitrary-shell-execution`, `no-destructive-sql`, and `block-personal-email-in-checkout`, alongside custom rules. Those four are the only ones the README names. Severity is expressed as CRITICAL, HIGH, MEDIUM or LOW, and the .env.example exposes two thresholds that govern the default posture: `DEFAULT_RISK_THRESHOLD=MEDIUM` and `AUTO_APPROVE_BELOW=LOW`. The second key is the one that decides which calls pass without a human looking at them.
The agent registry is the other half of the model. Each agent that has touched the gateway carries a human owner, a scope of PRODUCTION, STAGING or RESTRICTED, a hashed secret, and a last-seen timestamp. Status filters separate Active, Unregistered, Suspended and Deprecated agents. That registry is what makes the audit trail attributable to a person rather than to a process name.
Installing AEGIS with Docker Compose and running a first check
The README offers a one-line installer, `curl -fsSL https://aegistraces.com/install | sh`, which it says detects OS and architecture, downloads the release, and places the binary in `/usr/local/bin`. Piping a remote script into a shell is a decision you should make deliberately, so the repository also ships a compose file you can read first. The Makefile wraps the common paths.
Start both services in the background and build the images:
make upThe Makefile defines `up` as `docker compose up -d --build`. When it returns, the dashboard is on port 3000 and the gateway on port 8080, per the comment block at the top of docker-compose.yml. Tail the logs with `make logs`, which runs `docker compose logs -f`.
Configuration lives in `.env`. Copy the example and adjust only what you need:
GATEWAY_PORT=8080
DB_PATH=./agentguard.db
DEFAULT_RISK_THRESHOLD=MEDIUM
AUTO_APPROVE_BELOW=LOW
NEXT_PUBLIC_GATEWAY_URL=http://localhost:8080The comment above those keys states that most settings have sensible defaults. The two risk keys are the ones worth changing on day one, because they determine how much traffic reaches a human.
For local development against the Python SDK, the Makefile exposes an editable install:
make install-sdkThat target runs `pip install -e ./packages/core-schema/python` followed by `pip install -e ./packages/sdk-python`. The README also points at a PyPI package named `agentguard-aegis` and an npm package named `@justinnn/agentguard`. The repository does not state whether those published artifacts are built from this same tree, which is something to confirm before you depend on them.
To see the intended behaviour without wiring your own agent, the `demo/` directory holds runnable examples, including `demo/blocking_demo.py`, `demo/showcase_agent.py` and `demo/simple-gateway.js`. The README's demo section describes a Claude-powered research assistant that traces tool calls, blocks SQL injection, detects PII, and pauses for human approval. That is a demonstration, not a benchmark, and the repository publishes no throughput or latency figures for the gateway.
Where AEGIS stops being the right tool
The README makes a large promise about interception and then goes quiet on the mechanics of the interception itself. It does not document how the agent's tool calls are routed through the gateway, whether that is an SDK wrapper, a proxy, or a framework integration, nor which agent frameworks are supported beyond the topics list naming LangChain and MCP. Zero agent changes is a strong claim, and the documentation does not show the seam where it is achieved. Treat that as the first thing to establish from the source before you plan a rollout.
Rollback is the second gap. The README describes blocking and human approval but does not document what happens to an action that was blocked, whether it can be replayed, or how an approval is recorded and later verified. If your workflow needs a blocked call to be re-issued after review, the documentation does not describe that path.
Platform support is uneven. The download table lists macOS 11+ on Apple Silicon and Linux on Ubuntu 22.04+, Debian 12+ and RHEL 9+, with Windows marked as coming in 0.2 and a suggestion to use WSL2 in the meantime. Note the version numbering in the release list: v0.2.0 is dated 2026-06-29, v0.1.0 is dated 2026-05-20 and described as the first desktop release, and v1.2.5 is dated 2026-03-06. The 1.x tag predates the 0.x tags, which is worth understanding before you pin a version.
Finally, the gateway is a component you now operate. It holds state in a SQLite file at `DB_PATH`, it needs a healthcheck to pass before the cockpit starts, and it is the thing standing between your agent and its tools. If the gateway is down and your integration treats that as a pass-through, you have removed the control without noticing. The README does not describe fail-open versus fail-closed behaviour.
AEGIS versus framework-level guardrails
The obvious alternative is the guardrail machinery that agent frameworks already ship, such as callback handlers and tool-permission hooks in LangChain. The difference is architectural. Framework hooks run inside the agent process, configured per agent, and their enforcement depends on the agent code being written correctly. AEGIS runs as a separate service on port 8080 with its own datastore, so the policy is not something an agent can skip by being constructed differently, and the audit record lands outside the agent's process. The trade-off is real: you gain a control point you can reason about centrally, and you take on a network hop plus a service to keep alive.
A second alternative is observability tooling. The topics list includes llm-observability, but tracing and enforcement are different jobs. A tracer records that `DROP TABLE users` was called. AEGIS is designed to stop it. If your requirement is post-hoc analysis, a tracer is cheaper and does not sit in the execution path. If your requirement is that the call never reaches the database, you need something in front of the tool, which is the position AEGIS takes. The README's Threat coverage view, described as MITRE-ATLAS-style with 40 agent-attack techniques and per-tactic bars, is aimed at the second requirement rather than the first.
Maintenance, licensing and what the release history implies
The repository is not archived, and the last push was on 2026-09-06. The release cadence visible in the release list is uneven: v1.2.5 on 2026-03-06, v0.1.0 on 2026-05-20, and v0.2.0 on 2026-06-29. Between the most recent release and the last push there is roughly two and a half months of commits with no tagged release, so if you depend on releases rather than on `main`, you are working from a snapshot that trails the branch.
The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of what the licence identifier tells you, and it is not legal advice. Two adjacent files complicate the picture in ways you should read yourself rather than infer: the repository root contains both `COMMERCIAL.md` and `TRADEMARK.md`. A commercial document alongside an MIT codebase usually describes paid support, hosting, or an enterprise edition, and a trademark policy governs the name rather than the code. Neither changes your rights under MIT to the source, but both can affect what you may call your deployment. The README links to `COMMERCIAL.md`, so the project clearly intends some commercial motion, and the documentation does not say what it covers.
Upgrade cost is dominated by the datastore. The gateway writes to `DB_PATH`, defaulting to `/data/agentguard.db` inside the `gateway-data` volume. Any schema change between versions has to be applied to that file, and the README does not describe a migration command. Back up the volume before pulling a new image.
Editorial conclusion
Adopt AEGIS if your agents run tools against production systems and you need a block-before-execute layer plus a reviewable trail, and you are willing to run the gateway and cockpit yourself. Do not adopt it if you need Windows-native support today, or if you cannot accept that the README documents no rollback path for a blocked action. Verify first that the Python SDK and the npm package on the registries are the same code as this repository, and that the DB_PATH you configure points at storage you back up.
Frequently asked questions
What does AEGIS do?
It is a pre-execution firewall for AI agents. Every tool call is intercepted, classified, checked against policy, and blocked if it violates one, with a tamper-evident audit trail written alongside.
What is AEGIS in AI?
In this project, AEGIS is runtime policy enforcement for AI agents: a gateway that sits between an agent and its tools, plus a cockpit dashboard for traces, policies, approvals and threat coverage.
How do you use AEGIS?
Run the gateway and cockpit with `make up`, which is `docker compose up -d --build`, then open the dashboard on port 3000 and the gateway on port 8080. Configuration comes from `.env`, where `DEFAULT_RISK_THRESHOLD` and `AUTO_APPROVE_BELOW` set the approval posture.
What is AEGIS in cyber security?
Here it is a control placed in front of an agent's tools rather than a network appliance: policies such as `no-destructive-sql` and `no-arbitrary-shell-execution` block a call before it executes, and the Activity view shows which policy fired and which DSL condition matched.
Community notes