This release is a pre-release and may not be stable for production use.
Agent Loop Guard
Agent Loop Guard is an Apache-2.0 local safety and observability toolkit for coding agents. It combines a loop guard, MCP permission firewall, session replay, deterministic benchmark lab, and a Docker-backed sandbox technical preview.
The default setup uses a local mock provider, so the demo works without an external API key.
Install
Install the current alpha from PyPI. The installed command is alg:
pipx install agent-loop-guard-runtime
# or
uv tool install agent-loop-guard-runtime
Run once without a permanent installation:
uvx --from agent-loop-guard-runtime alg doctor
For development from this checkout:
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
alg setup
alg doctor
alg guard run
Open http://127.0.0.1:8787, then run Demo Lab or:
alg demo exact-loop
Default local gateway key:
alg_demo_key
Proxy Endpoints
OpenAI-compatible:
POST /v1/responses
POST /v1/chat/completions
GET /v1/models
Anthropic-compatible:
POST /v1/messages
POST /v1/messages/count_tokens
Connectivity probe:
HEAD /
Use Authorization: Bearer alg_demo_key or x-api-key: alg_demo_key.
alg setup creates a local YAML configuration and connection profiles for Codex, Claude Code, Cline, and OpenCode under .agent-loop-guard/profiles. Open http://127.0.0.1:8787, then run Demo Lab or alg demo exact-loop.
Modules
alg setup | doctor | status | open
alg guard run
alg mcp run | serve | validate-policy | test-server
alg replay import | export
alg bench dataset validate | run | compare | regression-check
alg sandbox create | exec | diff | apply | discard | export
- Guard detects exact request, tool, error, and sequence loops with Shadow and Enforce modes.
- MCP Firewall proxies stdio and Streamable HTTP, validates schemas, filters discovery, and applies YAML policies.
- Replay stores redacted traces, spans, events, costs, deterministic failure tags, and JSONL/OpenTelemetry exports.
- Benchmark Lab runs the bundled 30-task dataset through mock, HTTP, or CLI adapters and computes paired bootstrap confidence intervals.
- Sandbox Preview runs a copied workspace in a resource-limited Docker container and applies no changes before explicit approval.
Read the public documentation, Architecture, Threat Model, Benchmark Guide, and Sandbox Guide. A Russian overview is also available.
Guard Behavior
The guard implements:
- exact repeated request detection
- repeated tool call detection
- repeated upstream error detection
- repeated request sequence detection
- request and token limits
- project-level Shadow and Enforce modes
- manual session and agent pause/resume
- metadata-only logging by default
- JSON session export and aggregate CSV export
- trace runs, spans, events, replay UI, JSON export, and run comparison
Shadow Mode flags suspicious requests without blocking. Enforce Mode blocks requests when a blocking rule triggers.
MCP Firewall
Validate and run a stdio policy proxy:
alg mcp validate-policy app/mcp/presets/filesystem.yml
alg mcp run --policy app/mcp/presets/filesystem.yml -- your-mcp-server
For Streamable HTTP, configure a server under mcp.servers, run alg mcp serve, and connect to /mcp/{server_id}. Approval requests appear at /mcp. Raw arguments and secrets are redacted; audit records store hashes and policy metadata.
Session Replay
Every proxied model request now creates a replay trace automatically. Open:
http://127.0.0.1:8787/replay
The Replay view shows trace runs, model request spans, policy decision events, token totals, duration, source session links, JSON export, and a simple two-run comparison.
Replay ingest API:
POST /api/v1/traces
POST /api/v1/spans
POST /api/v1/events/batch
GET /api/v1/runs
GET /api/v1/runs/{trace_id}
GET /api/v1/runs/{trace_id}/export?format=json|jsonl|otel
POST /api/v1/runs/import
POST /api/v1/runs/{trace_id}/pin
POST /api/v1/compare
CLI transfer:
alg replay export TRACE_ID --format jsonl --output trace.jsonl
alg replay import trace.jsonl
Benchmark Lab
alg bench dataset validate
alg bench run --adapter mock --candidate baseline --output baseline.jsonl
alg bench run --adapter mock --variant regressed --candidate candidate --output candidate.jsonl
alg bench regression-check baseline.jsonl candidate.jsonl
Parquet, DuckDB, and MLflow are optional:
pip install -e ".[bench]"
The regression command exits 0 for no regression, 1 for a statistically supported regression, and 2 when the result is inconclusive.
Sandbox Preview
Docker must be installed and running first. The original project is not mounted into the container; the sandbox uses a private copy.
alg sandbox create .
alg sandbox exec SANDBOX_ID -- pytest -q
alg sandbox diff SANDBOX_ID
alg sandbox apply SANDBOX_ID --path app/example.py
alg sandbox discard SANDBOX_ID
Network is disabled by default. This is a defense-in-depth development tool, not a certified security boundary; read the threat model before using it with untrusted code.
Minimal trace ingest example:
curl -X POST http://127.0.0.1:8787/api/v1/traces ^
-H "Content-Type: application/json" ^
-d "{\"trace_id\":\"demo_trace\",\"task_id\":\"demo\",\"spans\":[{\"name\":\"tool.call\",\"start_ns\":1,\"end_ns\":2000000}]}"
Agent Setup
Codex CLI:
model = "demo-model"
model_provider = "agent_loop_guard"
[model_providers.agent_loop_guard]
name = "Agent Loop Guard"
base_url = "http://127.0.0.1:8787/v1"
env_key = "ALG_GATEWAY_KEY"
Claude Code:
set ANTHROPIC_BASE_URL=http://127.0.0.1:8787
set ANTHROPIC_AUTH_TOKEN=alg_demo_key
OpenCode:
{
"provider": {
"alg": {
"npm": "@ai-sdk/openai-compatible",
"name": "Agent Loop Guard",
"options": {
"baseURL": "http://127.0.0.1:8787/v1",
"apiKey": "{env:ALG_GATEWAY_KEY}"
},
"models": {
"demo-model": {"name": "Guarded model"}
}
}
},
"model": "alg/demo-model"
}
Cline:
API Provider: OpenAI Compatible
Base URL: http://127.0.0.1:8787/v1
API Key: alg_demo_key
Model ID: demo-model
VS Code Extension
The VS Code extension starts the local guard daemon, shows health in the status bar, opens dashboard and replay views, and copies agent connection settings.
Install it from the VS Code Marketplace or from the command line:
code --install-extension RIMUMURUDEV.agent-loop-guard-vscode
Install the Python runtime first, then use Agent Loop Guard: Setup Current Workspace:
pipx install agent-loop-guard-runtime
Run the extension from source:
cd extensions/vscode
npm run check
Then open this repository in VS Code, press F5, and run Agent Loop Guard: Start Guard in the Extension Development Host.
Package and install a local .vsix:
cd extensions/vscode
npm run package
code --install-extension agent-loop-guard-vscode-0.2.0.vsix
If alg is installed globally, keep agentLoopGuard.startMode as cli. To run from this checkout instead, set:
{
"agentLoopGuard.startMode": "source",
"agentLoopGuard.pythonPath": ".venv\\Scripts\\python.exe",
"agentLoopGuard.sourcePath": "C:\\path\\to\\agent-loop-guard"
}
After the guard is running, point agents at:
OpenAI base URL: http://127.0.0.1:8787/v1
Anthropic base URL: http://127.0.0.1:8787
API key: alg_demo_key
See extensions/vscode/README.md for all commands and settings.
Configuration
Create a config file:
alg init --path agent-loop-guard.yml
Run with it:
alg run --config agent-loop-guard.yml
Environment overrides include:
ALG_HOSTALG_PORTALG_STORAGE_URLALG_MODEALG_PROVIDERALG_GATEWAY_KEYALG_OPENAI_BASE_URLOPENAI_API_KEYALG_ANTHROPIC_BASE_URLANTHROPIC_API_KEY
Development
pip install -e ".[dev,docs]"
pytest -q
ruff check .
mkdocs build --strict
Run the documentation site locally:
mkdocs serve
The full contributor workflow is in CONTRIBUTING.md. Security assumptions and private reporting guidance are in SECURITY.md.
Docker:
docker compose up --build
Project Status
This repository is developed as an educational open-source project. Guard, MCP, Replay, and Benchmark are locally testable. Sandbox is a technical preview and its real Docker smoke-test runs only on Linux CI; it could not be executed on the current Windows machine because Docker is not installed. The Python runtime and VS Code extension are publicly available through PyPI and the VS Code Marketplace.
There is no telemetry, paid cloud, subscription, SLA, or closed feature set. Optional donations may be added later, but they do not influence architecture or priorities.
Limits
The toolkit only sees traffic routed through it. It does not provide enterprise IAM, distributed leases, legal audit guarantees, a kernel-level isolation guarantee, or hidden chain-of-thought capture. Full Content Logging is off by default and should not be enabled for sensitive data unless the data owner understands the risk.
Metadata
Release files for agent-loop-guard-runtime 0.6.0a3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_loop_guard_runtime-0.6.0a3.tar.gz | 77.8 kB | With provenance | Details for agent_loop_guard_runtime-0.6.0a3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_loop_guard_runtime-0.6.0a3-py3-none-any.whl | Python 3 | none | any | Details for agent_loop_guard_runtime-0.6.0a3-py3-none-any.whl |
Total release size: 177.4 kB
Release files / agent_loop_guard_runtime-0.6.0a3.tar.gz
| Download URL | agent_loop_guard_runtime-0.6.0a3.tar.gz |
|---|---|
| Size | 77.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8ff36702e2b86ada1f6232f8decbcc421ddd930f4f303bc00d8578f030a29edc
|
|
BLAKE2b-256 checksum How to use checksums |
7038040fda3c9558d461b49b6b5c4fc609eaaac177b1c08a742d72fc8ab34bb4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logRelease files / agent_loop_guard_runtime-0.6.0a3-py3-none-any.whl
| Download URL | agent_loop_guard_runtime-0.6.0a3-py3-none-any.whl |
|---|---|
| Size | 99.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
98d226056276f27965f1cd144d11438b0d3cc58ba7b3bbd75a3acebe64e6fc23
|
|
BLAKE2b-256 checksum How to use checksums |
9fdf498bc7795b476cd35c769da5044ec74cf19086cb29a3b6f81f9ac713ab59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logSecurity for agent-loop-guard-runtime 0.6.0a3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agent_loop_guard_runtime-0.6.0a3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.