AegisFlow

AegisFlow is a local-first policy gateway for coding agents. Allow, review, or block routed MCP actions and verify signed session evidence.

Start here

Run a governed PR-writer policy locally. No provider key or paid service required.

git clone https://github.com/saivedant169/AegisFlow.git
cd AegisFlow/starter-kit
./install-pr-writer.sh

Installer builds AegisFlow, starts local gateway and admin services, loads PR-writer policy, and checks allow, review, and block decisions.

Connect an agent after checks pass:

• Claude Code setup
• Cursor setup
• PR-writer quickstart
• Full proof walkthrough

What gets enforced

Routed MCP tool calls become an ActionEnvelope. Tool policy evaluates protocol, tool, target, capability, actor, task, and session context. Model API requests use input and output policy; they do not dispatch external tools. See runtime support and verification.

Routed action	Example	Default PR-writer decision
Read repository content	github.get_file_contents	allow
Run tests	shell.go_test	allow
Delete files recursively	shell.rm	block
Open a pull request	github.create_pull_request	review
Merge or force push	github.merge_pull_request	block
Read database rows	sql.select	allow with sql-explorer
Change database rows	sql.update	review with sql-explorer

Review decisions enter an approval queue. Optional upstream credential issuance is disabled in the development candidate pending broker hardening. See candidate behavior and migration; published v0.9.0 has a different persistence and credential contract.

MCP client -> authenticated gateway -> tool policy -> decision evidence
                                           |
                              allow -> upstream -> result evidence
                              review -> approval queue -> matching retry
                              block -> error response

Model API client -> input policy -> provider -> output policy -> response

Boundary support

Path	Governed behavior	Status
MCP remote gateway	tools/list, tool calls, arguments, review resume	supported
MCP stdio bridge	Routed tool calls and gateway failures	supported
OpenAI-compatible API	Input, output, streams, tool definitions, tool calls	supported
Anthropic Messages API	Input, output, streams, optional tool passthrough	supported
Built-in editor file or shell tools	Only covered when routed through MCP or another configured boundary	not intercepted directly
Standalone shell, SQL, GitHub, and HTTP gate libraries	Library behavior and unit tests	experimental, not wired

messages_api.tool_passthrough remains off by default. Enable it only after testing selected provider tool loops.

Install

Verified release binary

curl -fsSL https://raw.githubusercontent.com/saivedant169/AegisFlow/v0.9.0/scripts/install.sh | AEGISFLOW_VERSION=v0.9.0 sh

Installer downloads SHA256SUMS from same release and rejects mismatched binaries.

Homebrew

brew install saivedant169/tap/aegisflow
brew install saivedant169/tap/aegisctl

Go

go install github.com/saivedant169/AegisFlow/cmd/[email protected]
go install github.com/saivedant169/AegisFlow/cmd/[email protected]

Source builds require Go 1.26.9 or later.

Container

docker run --rm -p 8080:8080 -p 8081:8081 -p 8082:8082 \
  saivedant169/aegisflow:0.9.0

Same image also publishes at ghcr.io/saivedant169/aegisflow:0.9.0.

Docker Compose

git clone https://github.com/saivedant169/AegisFlow.git
cd AegisFlow
docker compose -f deployments/docker-compose.yaml up --build

Gateway listens on 8080, admin API and dashboard on 8081, MCP gateway on 8082.

Policy packs

Pack	Intended use	Read	Risky write	Destructive action
readonly	Inspection and analysis	allow	block	block
pr-writer	Read, test, edit, open PR	allow	review	block
docs-writer	Documentation changes	allow	review	block
infra-review	Infrastructure planning	allow	review	block
sql-explorer	Data exploration	allow	review	block

Policy files and tuning notes live under starter-kit/policies.

Evidence and approvals

# Check gateway, admin API, providers, approvals, and evidence state
./bin/aegisctl status

# List pending actions
./bin/aegisctl pending

# Approve one exact action
./bin/aegisctl approve <action-id> "reviewed diff"

# Export and verify a session
./bin/aegisctl evidence export <session-id> --file evidence.json
./bin/aegisctl verify --session <session-id>

Memory storage remains default. Enable SQLite when approvals and evidence must survive restart:

state:
  enabled: true
  sqlite_path: "data/aegisflow.db"

Set AEGISFLOW_EVIDENCE_KEY from a secret manager before starting. Same key authenticates approval rows and evidence records while staying outside SQLite. AEGISFLOW_STATE_DB can override configured path. SQLite mode supports one running AegisFlow instance; it is not shared state for multiple replicas.

Run restart, replay, changed-argument, and evidence-tamper checks with make e2e-approval-security.

Release verification

v0.9.0 release includes checksums, Sigstore bundle, SPDX SBOM, and GitHub build provenance.

asset=aegisflow-linux-amd64
grep "  ${asset}$" SHA256SUMS | sha256sum --check -
cosign verify-blob \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity-regexp '^https://github\.com/saivedant169/AegisFlow/\.github/workflows/release\.yaml@refs/tags/v0\.9\.0$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS
gh attestation verify aegisflow-linux-amd64 \
  --repo saivedant169/AegisFlow

See v0.9.0 release notes for upgrade steps and known limits.

Documentation

Need	Document
First local request	Getting started
Governed PR example	PR-writer proof
Runtime components	Architecture
API endpoints	OpenAPI specification
Configuration	Annotated config
Deployment checks	Production checklist
Incident response	Operations runbook
Metrics and traces	Observability
Performance method	Performance
Threat boundary	Threat model
Provider and policy problems	Troubleshooting

Development

make build
make test
make vuln
make smoke

Current CI runs formatting, build, race tests, vulnerability checks, installer verification, Docker smoke tests, CodeQL, and OpenSSF Scorecard.

Contribution rules: CONTRIBUTING.md. Security reports: SECURITY.md. Questions and policy examples belong in GitHub Discussions.

License

Apache License 2.0. See LICENSE.