⬡ LOCAL-FIRST · ZERO DATA EXPOSURE · OPEN SOURCE

GUARDIAN RUNTIME

The ultimate local firewall for autonomous AI coding agents. Guardian intercepts every prompt and response to enforce strict FinOps budgets, prevent secret leaks, and compress token payloads all before your data ever leaves your machine.

⭐ GITHUB REPO pip install guardian_runtime VIEW QUICKSTART

$ pip install "guardian_runtime[all]"
✓ Successfully installed guardian_runtime-1.1.1

$ guardian_runtime proxy --port 8080
✓ Proxy started on port 8080. Zero-Config Mode Active.

# Claude Code tries to send an .env file...
🚨 [SECRET_DETECTED] AWS key AKIAIOSFODNN7EXAMPLE found — BLOCKED

# Agent gets stuck in an infinite loop...
🚨 [BUDGET_EXCEEDED] Daily budget of $10.00 exceeded. Current spend: $10.05 — BLOCKED

$

// THE WHY, WHAT & HOW

THE PROBLEM & THE SOLUTION

THE PROBLEM

💸 The FinOps Risk

Autonomous coding agents operate in infinite loops. A single stuck agent repeatedly fetching massive files can quietly rack up a $100+ API bill overnight, leaving you with zero visibility until the invoice arrives.

THE GUARDIAN SOLUTION

Hard Budgets & Dual-Layer Compression: Enforce strict local token budgets (e.g., $5.00/day). For further optimization, enable Terse Mode—a dual-layer compression engine that aggressively optimizes input context and forces concise LLM outputs. In real-world benchmarks, Terse Mode reduces output API costs by 40–70% without sacrificing technical accuracy.

                            optimizer:

                              enabled: true

                              terse_mode: true

THE PROBLEM

🔒 The Security Risk

AI coding assistants require deep, unrestricted access to your local workspace. Without an outbound firewall, an agent will silently upload your .env files, AWS credentials, and proprietary internal IP directly to third-party LLM providers.

THE GUARDIAN SOLUTION

Zero-Latency Secret Scanners: Guardian operates as a local reverse proxy, scanning every outbound payload in milliseconds. If an API key or proprietary secret is detected, the request is instantly destroyed before it ever touches the network. This guarantees zero-trust protection for your environment variables.

                            security:

                              scan_secrets: true

                              action: "block"

THE PROBLEM

🏛 The Compliance Risk

Feeding production database dumps or unauthorized Personally Identifiable Information (PII) into public LLM endpoints severely violates modern privacy regulations like GDPR, HIPAA, and DPDP.

THE GUARDIAN SOLUTION

Local PII & Anonymization Engine: Built-in Regex and local ML scanners act as a last line of defense, proactively detecting and redacting sensitive user data. It automatically masks data so you can safely use public LLMs without risking regulatory fines.

                            compliance:

                              anonymize_pii: true

                              entities: ["EMAIL", "PHONE"]

// CAPABILITIES

PLATFORM FEATURES

💰

Hard Local Budgets

Configure a strict daily budget so runaway agents or infinite loops can't drain your API credits. Stops the bleeding instantly with zero cloud dependency.

FinOps Cost Control

🔑

ML-Powered Secret Firewall

Uses Microsoft Presidio for high-accuracy NLP scanning (emails, phones) and rigorous Regex fallbacks for API keys. Blocks threats locally.

PRESIDIO REGEX ZERO-LATENCY

📉

Token Optimizer

Automatically trims redundant tokens, conversational filler, and excessive whitespace from prompts before they hit the LLM. Passively saves you money on every request.

Token Reduction Auto-Savings

🌐

Universal Local Proxy

A built-in proxy server lets you intercept traffic from CLI agents (Claude Code, Aider) without modifying their source code. Perfect for solo developers or internal tools.

Claude Code Aider LangChain

🏴‍☠️

Jailbreak & Unsafe Command Defense

Pattern-matched detection for DAN variants, instruction overrides, and system prompt extraction attempts. Stops adversarial prompts from hijacking your agent.

DAN Injection

📊

Session Analytics Dashboard

Automatically tracks tokens, costs, and blocked requests for all your CLI tools in real-time. Instantly view your exact daily spend with the analytics command.

Visibility CLI Metrics

// DEPLOY IN MINUTES

QUICKSTART

Install

Zero external dependencies for core detection. Optional extras for proxy and dashboard.

pip install "guardian_runtime[all]"

Wrap your LLM call

Drop Guardian between your app and any LLM. One import, one object, fully governed calls.

from guardian_runtime import
                        GuardianRuntime
                        
                        gr = GuardianRuntime()
                        
                        # Your normal LLM call — now governed
                        
                        response = gr.complete(
                        
                          model="gpt-4o",
                        
                          messages=[{"role": "user", "content": user_input}]
                        
                        )
                        
                        # response.blocked → True if threat detected
                        
                        # response.violations → list of what was caught
                        
                        # response.estimated_cost_usd → spend this call

Configure your policy (optional)

Guardian works zero-config out of the box. But if you want to enforce strict budgets or enterprise PII blocking, create a policy.yaml file.

version: "1.0"
                        
                        agents:
                        
                          default:
                        
                            cost:
                        
                              daily_budget: 10.00 # Strict daily budget limit in USD ($)
                        
                              max_input_tokens: 50000
                        
                            input_guard:
                        
                              pii_detection: true # Opt-in for enterprise SSN/Credit Card blocking

Use the CLI Tools

Guardian comes with built-in terminal tools for management and local logging.

                        # Initialize local log directories (~/.guardian_runtime/logs)

                        guardian_runtime init

                        # View Session Analytics (Cost & Tokens per CLI tool)

                        guardian_runtime analytics

                        # Tail live security threat logs

                        guardian_runtime logs --tail 20

                        # Start the local interception proxy

                        guardian_runtime proxy --port 8080

// MECHANICS

WHAT HAPPENS WHEN GUARDIAN BLOCKS?

01. WHERE WILL THEY SEE IT?

If using the Proxy, developers see the block instantly inside the UI of their tool (e.g. Claude Code chat) and in the background proxy logs.

If using the SDK, it surfaces in their standard Python server logs.

02. HOW IS IT BLOCKED?

Zero crashes. In Proxy mode, Guardian cleanly returns a standard Local Error error. This ensures CLI agents display an error message gracefully instead of crashing their process.

In SDK mode, it raises a standard Python Exception.

03. WHAT DO THEY SEE?

No obscure stack traces. They see a completely transparent, actionable string telling them exactly what policy they violated.

Example: 🚨 [BUDGET_EXCEEDED] Daily budget of $10.00 exceeded.

// INTEGRATION GUIDES

HOW TO USE GUARDIAN

Custom Python Apps (Chatbots, RAG)

If you are building your own AI application in Python, use the SDK directly.
This gives you full programmatic control over policies and error handling.

                        # 1. Install the package

                        pip install "guardian_runtime[all]"

                        # 2. In your code, wrap your LLM calls

                        from guardian_runtime import GuardianRuntime

                        gr = GuardianRuntime.from_policy("policy.yaml")

                        # Instead of calling OpenAI/Anthropic directly:

                        response = gr.complete(

                          messages=[{"role": "user", "content": "My SSN is 123-45-6789"}]

                        )

$ python run_chatbot.py

# Guardian intercepts before the network call:
Traceback (most recent call last):
File "run_chatbot.py", line 12, in <module>
GuardianRuntimeBlockedError: 🚨 [PII_DETECTED] 1 Policy Violations:
- SSN number found in prompt. Severity: HIGH.

Developers (Claude Code or Aider Users)

Stop CLI agents from getting stuck in loops and blowing your API budget. Guardian's zero-config local proxy sits between your agent and Anthropic/OpenAI.

                        # 1. Install Guardian and start the Proxy

                        pip install "guardian_runtime[all]"

                        guardian_runtime proxy --port 8080

                        # 2. Tell Claude to use the proxy

                        export ANTHROPIC_BASE_URL=http://localhost:8080

                        claude

# Claude attempts to read an .env file to fix a bug...

Claude> I will check your .env file for the AWS credentials.
Reading .env...
Sending context to Anthropic...

# Guardian Proxy blocks the HTTP request instantly:
Error: HTTP 403 Forbidden. 🚨 [SECRET_DETECTED] AWS key AKIAIOSFODNN7EXAMPLE found.

Visual IDEs (Cursor, Windsurf)

GUI editors have deep codebase access. Guardian stops them from sending highlighted secrets to the cloud.

                        # 1. Start the Proxy in your terminal

                        guardian_runtime proxy --port 8080

                        # 2. In Cursor Settings (Cmd+,)

                        Navigate to Models > Override Base URL

                        Set it to: http://localhost:8080

# You ask Cursor to explain an AWS config file...

Cursor> Explain the code in config.json
Reading config.json...

# Guardian Proxy blocks it locally before it hits the internet:
Error: HTTP 403 Forbidden. 🚨 [SECRET_DETECTED] AWS key found.

Enterprise Teams (LangChain, AutoGen)

Working at a company? Use Guardian to enforce strict policies across all internal AI tools so your employees don't accidentally leak customer PII or proprietary code.

                        # Wrap any LangChain or AutoGen client

                        from langchain_openai import ChatOpenAI

                        # Point your framework to the local proxy:

                        llm = ChatOpenAI(

                          model="gpt-4o",

                          base_url="http://localhost:8080"

                        )

                        chain.invoke({"input": user_query})

# LangChain Trace:
[chain/start] [1:chain:AgentExecutor] Entering Chain run
[llm/start] [1:chain:AgentExecutor > 2:llm:ChatOpenAI] Entering LLM run

[llm/error] [1:chain:AgentExecutor > 2:llm:ChatOpenAI] [0ms] LLM run errored
BadRequestError: Error code: 400 - {'error': {'message': '🚨 [BUDGET_EXCEEDED] Daily budget of $50.00 exceeded.', 'type': 'policy_violation'}}

Document Converter (Zero-Code)

If you process large PDFs or Word documents for RAG, they often contain massive amounts of formatting bloat. Use the built-in CLI to instantly clean and convert them into pure Markdown.

                        # Simply pass any PDF or DOCX file to the CLI:

                        guardian_runtime convert <path/to/input.pdf> --out <path/to/output.md>

$ guardian_runtime convert <path/to/input.pdf> --out <path/to/output.md>

⛨ GuardianRuntime Document Converter
Processing: financial_report.pdf...

✓ Conversion Complete!
  • Original File: financial_report.pdf
  • Token Count: 14,205
  • Saved to: clean_report.md

Session Analytics (FinOps)

Guardian automatically tracks your spend across every CLI tool and script you use. Never wonder how much a Claude Code refactor cost you again.

                    # At the end of the day, just run:

                    guardian_runtime analytics

                    # Or see all-time history:

                    guardian_runtime analytics --all

$ guardian_runtime analytics

⛨ GuardianRuntime Session Analytics (Today)
──────────────────────────────────────────────

Claude Code
Cost: $2.3100
Requests: 54
Blocked: 3 (3 secret_detected)
Tokens: 82,000

// COMMAND LINE INTERFACE

EXHAUSTIVE CAPABILITIES & CLI

guardian_runtime proxy

The Security Firewall

Starts the local HTTP interception server. This is the core engine for protecting tools that you cannot edit the source code for (like Cursor or Claude Code).

FLAGS:
--port, -p <int> (Default: 8080)
--host <str> (Default: 127.0.0.1)
--policy <path> (Custom policy.yaml)
--reload (Dev mode)

$ guardian_runtime proxy --port 8080

⛨ GuardianRuntime Runtime Proxy
─────────────────────────────────────────
Listening on : http://127.0.0.1:8080
Policy : Default (Zero-Config)

guardian_runtime convert <path>

Document Analysis & Compression

Converts massive PDF, DOCX, and XLSX files into highly compressed, token-optimized Markdown to prevent wasting tokens on hidden formatting bloat in RAG pipelines.

ARGS/FLAGS:
<path> (Input file path)
--out, -o <path> (Output file path)

$ guardian_runtime convert <path/to/input.pdf> --out <path/to/output.md>

✓ Conversion Complete!
• Original File: input.pdf
• Token Count: 14,205
• Saved to: clean.md

guardian_runtime scan <text>

Manual Threat Verification

Performs a local security scan on a specific text string using the ML InputGuard. Use this to verify exactly what the firewall will catch before sending a payload.

$ guardian_runtime scan "Key is AKIAIOSF..."

🛑 Scan failed! Threats detected:
- [HIGH] secret_detected: AWS Access Key ID

guardian_runtime analytics

FinOps Cost Tracking

Prints a beautiful terminal summary of API costs, token usage, and intercepted threats broken down by tool.

FLAGS:
--all (Show all-time historical data)

$ guardian_runtime analytics

Claude Code
Cost: $2.3100
Blocked: 3 (secret_detected)

Additional Administration Commands

guardian_runtime dashboard

Launches a React-based local Web UI tracking costs and threats on port 3000.

guardian_runtime logs

Tails the local JSONL event stream (`tail -f ~/.guardian_runtime/logs/events.jsonl`). Perfect for debugging exact block reasons.

guardian_runtime init

Generates a boilerplate policy.yaml file for customizing budgets or ML scanners.

guardian_runtime validate

Checks your policy.yaml for syntax errors before you restart the proxy.

guardian_runtime --help

Prints the global help menu listing all available commands and flags.

guardian_runtime status

Shows the health of the local installation.

guardian_runtime clean

Deletes your entire ~/.guardian_runtime directory. Use this to permanently delete local analytics, logs, and custom policies.

GUARDIAN RUNTIME

THE PROBLEM & THE SOLUTION

💸 The FinOps Risk

🔒 The Security Risk

🏛 The Compliance Risk

SUPPORTED INTEGRATIONS

THE SECURITY PIPELINE

PLATFORM FEATURES

QUICKSTART

WHAT HAPPENS WHEN GUARDIAN BLOCKS?

01. WHERE WILL THEY SEE IT?

02. HOW IS IT BLOCKED?

03. WHAT DO THEY SEE?

HOW TO USE GUARDIAN

EXHAUSTIVE CAPABILITIES & CLI