⬡ LOCAL-FIRST · ZERO DATA EXPOSURE · OPEN SOURCE

GUARDIAN RUNTIME

Guardian Runtime sits securely on your machine, acting as a bodyguard for your code.
Whenever you use AI tools like Cursor or Claude Code, it scans every prompt locally to stop sensitive secrets and PII from reaching the cloud.
It also tracks your API spending to prevent surprise bills, all without slowing you down.

⭐ GITHUB pip install guardian_runtime QUICKSTART →

bash — guardian_runtime

$ pip install "guardian_runtime[all]"

✓ Successfully installed guardian_runtime-1.3.0


$ guardian_runtime proxy --port 8080

✓ Proxy active on :8080 · OpenAI · Anthropic · Gemini native


# Claude Code sends .env file with AWS key...

🚨 [GUARDIAN BLOCKED] AWS key AKIAIOSFODNN7EXAMPLE found on line 3.

 Type y/n to proceed or cancel › 


# Daily budget enforced automatically...

🚨 [BUDGET_EXCEEDED] Spend $5.02 › limit $5.00. Request blocked.

// THE PROBLEM

WHY YOU NEED GUARDIAN

AI coding agents need full access to your codebase. That creates three dangerous, silent risks.

THE PROBLEM

💸 Cost Runaways

Agents operate in loops. A stuck agent retrying a bug fix or dumping a 1 GB log file into context can generate a $100+ API bill overnight with zero warning.

GUARDIAN SOLUTION

Hard daily budgets enforced locally. Set daily_budget: 5.00 and Guardian blocks any request that would exceed it — instantly, zero cloud dependency. Terse Mode cuts output tokens by 40–70%.

THE PROBLEM

🔒 Secret Leaks

Agents read your entire workspace. One .env file with an AWS key in context, and that credential silently travels to an OpenAI or Anthropic cloud server.

GUARDIAN SOLUTION

Zero-latency secret scanner checks every prompt locally before it leaves your machine. AWS keys, GitHub tokens, OpenAI keys, Stripe secrets — all caught at line-number precision. Blocks with an in-chat y/n override.

THE PROBLEM

🏛 Compliance Risk

Sending production database content or PII (SSNs, emails, Aadhaar numbers) to public LLM APIs violates GDPR, HIPAA, and India's DPDP Act.

GUARDIAN SOLUTION

Local PII scanner detects Aadhaar, PAN, SSN, credit cards, emails, phone numbers, and passports before they reach the network — completely offline, zero cloud dependency.

// SECURITY PIPELINE

HOW IT WORKS

Every prompt passes through a strict local security pipeline — entirely on your machine — before being forwarded to the cloud.

👤 SOURCE Agent / Dev

prompt

🛡️ GUARDIAN RUNTIME · LOCALHOST:8080

SECRET SCAN

AWS_KEY=AKIA··· DB_URL=postgres

TOKEN COUNT

8,012 TOKENS ~$0.0042

DOC CONVERT

📄 → 📝

BUDGET GUARD

DAILY SPEND

$3.41 / $5.00

🚨 BLOCKED — Secret detected on line 3 · Type y to proceed or n to cancel

clean

☁️ CLOUD LLM OpenAI / Claude / Gemini

response

🔎 OUTPUT GUARD Audit Response

safe

✓ DELIVERED Optimized Response

Prompt Intercepted

Your AI tool sends its prompt to localhost:8080 instead of the cloud. Zero code changes needed — just point the base_url or set an env var.

File Routing

Attached files are auto-detected by type. Code files (.env, .py, .json) go to the secret scanner. Documents (PDF, DOCX) are converted to lean Markdown.

Security Scan

Every line is scanned: AWS/GitHub/OpenAI keys, PII (SSN, Aadhaar, emails), and 40+ jailbreak patterns. The exact line number is reported on any match.

Interactive Block

Instead of crashing your session, Guardian replies inside your chat: "Secret found on line 3. Proceed? y/n" — you stay in the flow.

Budget Enforcement

Tokens are counted with tiktoken before forwarding. If today's spend would exceed your daily_budget, the request is blocked instantly.

Safe Forwarding

The clean, verified, optimized prompt reaches the LLM. The response is scanned on return. Cost is logged locally. Nothing leaves without clearance.

// CAPABILITIES

PLATFORM FEATURES

🔑

Secret & Credential Scanner

Regex patterns detect AWS keys, GitHub tokens, OpenAI/Anthropic keys, Stripe secrets, Razorpay, Groq, and generic KEY=value patterns in real-time. Reports the exact line number.

RegexZero-LatencyLine-Number

👤

PII Detector

Detects Aadhaar, PAN, UPI, SSN, credit cards, email addresses, phone numbers, and passport numbers before they reach any cloud endpoint. Fully offline.

PIIGDPRDPDPOffline

🛡️

Jailbreak Guard

40+ regex patterns detect DAN mode, "ignore instructions", role-play attacks, and prompt injection attempts. Stops adversarial prompts from hijacking your agent.

DANInjection40+ patterns

💬

Interactive y/n Override

When a secret or PII is detected, Guardian responds inside your chat window as the assistant — telling you exactly what was found and on which line — then asks if you want to proceed.

In-Chaty/nAll Providers

📄

Document Converter

PDF, DOCX, XLSX, and HTML files are automatically converted to lean Markdown using Microsoft MarkItDown. Saves thousands of tokens per request. Also available as a CLI command.

PDFDOCXMarkItDownToken Savings

💸

Hard Budget Caps

Set daily_budget: 5.00 in your policy.yaml. Guardian counts tokens with tiktoken and blocks any request that would push you over your limit.

FinOpstiktokenHard Limit

⚡

Terse Mode

Automatically injects a system prompt forcing the LLM to reply in concise shorthand. Reduces output tokens by 40–70% in real-world benchmarks without sacrificing technical accuracy.

Input Optimizer40–70% savings

🌐

Universal API Proxy

Speaks OpenAI, Anthropic, and native Google Gemini (/v1beta/models/{model}:generateContent) formats. Works with any tool that allows setting a custom base URL.

OpenAIAnthropicGemini v1betaStreaming

📊

Session Analytics

Tracks tokens, costs, blocked requests, and document conversions per session locally in ~/.guardian_runtime/. Check live via GET /stats or the CLI.

JSONL Logs/stats endpointCLI

COMPLIANCE COVERAGE

GDPR

HIPAA

DPDP (India)

SOC 2 Aligned

Zero Network

// DEPLOY IN MINUTES

QUICKSTART

No signup. No cloud account. Zero configuration required.

Install

Full install with all providers, document converter, and ML scanner.

pip install "guardian_runtime[all]"

Start the proxy

One command. Starts listening on port 8080 for OpenAI, Anthropic, and Gemini formats.

guardian_runtime proxy --port 8080

Connect your AI tool

No code changes. Just point the base URL to localhost:

# Claude Code
export ANTHROPIC_BASE_URL=http://localhost:8080
claude

# Aider
export OPENAI_API_BASE=http://localhost:8080/v1
aider

# Gemini CLI
export HTTPS_PROXY=http://localhost:8080
gemini

# Cursor / Windsurf — Settings → AI → Base URL
http://localhost:8080/v1

Use the Python SDK (optional)

Drop Guardian into your own application as a governed LLM wrapper:

from guardian_runtime import GuardianRuntime, GuardianRuntimeBlockedError

gr = GuardianRuntime() # zero-config

try:
    response = gr.complete(
        model="gpt-4o",
        messages=[{"role": "user", "content": user_input}],
        raise_on_block=True
    )
    print(response.content)
except GuardianRuntimeBlockedError as e:
    print(f"Blocked: {e.response.violations[0].detail}")

Configure a policy (optional)

Guardian works zero-config out of the box. Customize via guardian_runtime init:

version: "1.0"
agents:
  default:
    llm:
      provider: openai
      default_model: gpt-4o

    input_guard:
      scanner_enabled: true
      jailbreak_detection: true

    cost:
      daily_budget: 5.00 # Hard block at $5/day
      max_input_tokens: 20000 # Block oversized context

    optimizer:
      enabled: true
      terse_mode: true # Cuts output tokens 40–70%

// UNIVERSAL COMPATIBILITY

INTEGRATIONS

Guardian works with any AI tool that allows setting a custom base URL — no source code modification required.

💻

Visual IDEs

Cursor, Windsurf, VS Code via Cline/RooCode

⌨️

Terminal Agents

Claude Code, Aider, GitHub Copilot CLI

⚙️

Frameworks

LangChain, AutoGen, LlamaIndex, CrewAI

☁️

LLM Providers

OpenAI, Anthropic, Google Gemini

🔌

API Formats

OpenAI · Anthropic · Gemini v1beta native

Claude Code / Aider (Terminal Agents)

CLI agents operate autonomously and can silently upload .env files to the cloud. Guardian sits between them and Anthropic/OpenAI.

guardian_runtime proxy --port 8080

export ANTHROPIC_BASE_URL=http://localhost:8080

claude

# Agent tries to upload .env...

🚨 [GUARDIAN BLOCKED] secret detected on line 1

 AWS_KEY=AKIAIOSFODNN7EXAMPLE

 Type y/n to proceed ›

Cursor / Windsurf (Visual IDEs)

GUI editors have deep codebase access. Guardian stops Cursor from sending highlighted secrets to the cloud when you ask it to explain a file.

# 1. Start proxy
guardian_runtime proxy --port 8080

# 2. Cursor Settings → Models → Override Base URL
http://localhost:8080

# You ask: "explain this AWS config"

🚨 [GUARDIAN BLOCKED]

 PII detected: email address on line 7

 Proceed? y/n ›

LangChain / AutoGen (Frameworks)

Agentic frameworks that spawn multiple communicating nodes can rapidly consume tokens. Guardian acts as a central cost-tracking hub.

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4o",
    base_url="http://localhost:8080/v1",
    api_key="sk-proj-..."
)

BadRequestError: 🚨 [BUDGET_EXCEEDED]

Daily spend $50.04 exceeds limit $50.00.

# Entire agent chain stops cleanly.

Python SDK (Production Apps)

Building a chatbot, RAG pipeline, or internal tool? Use Guardian as a drop-in replacement for the OpenAI/Anthropic SDK.

from guardian_runtime import GuardianRuntime

gr = GuardianRuntime.from_policy("policy.yaml")
response = gr.complete(messages=[...])

# response.blocked → True if threat caught
# response.violations → list of what was found
# response.estimated_cost_usd → spend this call

✓ response.blocked = False

✓ response.content = "Here is the answer..."

 estimated_cost_usd = 0.0021

 tokens_in = 312, tokens_out = 89

Document Converter (CLI)

Convert PDF, DOCX, or XLSX files to clean Markdown before sending to any AI chat interface. Eliminates formatting bloat, saving thousands of tokens.

guardian_runtime convert report.pdf --out clean.md


# Or check live session stats:
guardian_runtime analytics

curl http://localhost:8080/stats

⛨ GuardianRuntime Document Converter

Processing: financial_report.pdf


✓ Conversion Complete!

 Token Count : 14,205

 Saved to : clean.md

// COMMAND LINE INTERFACE

CLI REFERENCE

Security Firewall

guardian_runtime proxy

Starts the local HTTP interception proxy. Core engine for protecting tools you cannot modify.

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

⛨ Proxy active on http://127.0.0.1:8080

 Mode: Zero-Config · Providers: All

Document Converter

guardian_runtime convert <file>

Converts PDF, DOCX, XLSX to token-optimized Markdown. Strips all formatting bloat.

<path> (Input file)
--out, -o <path> (Output markdown)

✓ Token Count: 14,205

✓ Saved to: clean.md

Manual Threat Check

guardian_runtime scan "<text>"

Run the secret + PII scanner on any text string. Use this to test exactly what the firewall catches before sending a payload.

🛑 [HIGH] secret_detected

 AWS Access Key ID found on line 1

FinOps Tracker

guardian_runtime analytics

Prints today's token usage, API costs, blocked requests, and document conversions. All sourced from local JSONL logs.

--all (Show all-time history)

Claude Code

Cost $2.31 · Requests 54 · Blocked 3

Additional Commands

guardian_runtime init

Generate a boilerplate policy.yaml in the current directory.

guardian_runtime validate

Check your policy.yaml for syntax errors before restarting the proxy.

guardian_runtime logs

Tail the live JSONL event stream in real-time. Perfect for debugging blocked requests.

guardian_runtime status

Show health of the local installation and ML models.

guardian_runtime clean

Permanently delete all local logs, analytics, and custom policies from ~/.guardian_runtime/.

GET /stats

Live REST endpoint: curl http://localhost:8080/stats returns today's cost, tokens, and blocks.

GUARDIAN RUNTIME

WHY YOU NEED GUARDIAN

HOW IT WORKS

PLATFORM FEATURES

QUICKSTART

INTEGRATIONS

CLI REFERENCE

STAR HISTORY