Guardian Runtime

// THE WHY, WHAT & HOW

THE PROBLEM & THE SOLUTION

THE PROBLEM

💸 The FinOps Risk

Autonomous agents run in loops. If they get stuck retrying a bug fix, you can wake up to a $100 API bill overnight. You have zero visibility until the bill arrives.

THE GUARDIAN SOLUTION

Hard Budgets & Caveman Mode: Tracks every token locally with a strict $5.00/day limit. Use Caveman Mode to drastically slash expensive output tokens while maintaining full technical accuracy.

                            optimizer:

                              enabled: true

                              caveman_mode: true

THE PROBLEM

🔒 The Security Risk

Coding agents require full codebase access. If you leave an AWS_SECRET_KEY in a .env file, the agent will silently upload it to a third-party LLM provider.

THE GUARDIAN SOLUTION

Zero-Latency Secret Scanners: Scans every prompt for keys and secrets locally. Drops malicious requests before they reach the internet.

THE PROBLEM

🏛 The Compliance Risk

Sending unauthorized PII (like customer emails in a test database) to foreign LLM APIs violates privacy regulations like GDPR and DPDP.

THE GUARDIAN SOLUTION

Local PII Blocking: Regex and ML scanners prevent sensitive user data from leaving your infrastructure.

// 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 HTTP 400/403 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.

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