The KAVLR Chronicles: How We Built an AI Terminal Leash That Blocked Its Own Deletion 🐯🛡️

If you’ve been following the HYNAWEB journey, you know we are building the secure infrastructure for the AI era. But the path from "thought experiment" to "globally published NPM package" is never a straight line.

Today, I’m pulling back the curtain on KAVLR, our fail-closed runtime security gate for autonomous AI agents, and the brutal, emotional journey of building it entirely on a $150 Android phone using Termux.

🏗️ The Technical Reality: How KAVLR Works

KAVLR is designed to intercept and evaluate terminal commands executed by AI agents (like Cursor or Claude Code). The core philosophy, brilliantly validated by senior security engineer @rudratosh, is simple: Grade the semantic action, not the text.

As he pointed out, string-matching fails against base64 encoding, obfuscation, and shell-outs. If you only scan the text, you miss the intent. KAVLR fixes this by evaluating the actual execution boundary. executed by AI agents (like Cursor or Claude Code). The core philosophy, validated by senior security engineers, is simple: Grade the semantic action, not the text. String-matching fails against base64 encoding, obfuscation, and shell-outs.

The Architecture

• Client Interface: Node.js CLI (@hynaweb/kavlr) parsing shell input and enforcing local execution.
• Fast-Path Policy Engine: Supabase PostgreSQL checking static rules (e.g., npm install = ✅, curl = ❌). -- Semantic Grading: Supabase Edge Functions (Deno) calling the Groq API, guided by a rigorous 90-Article Constitutional AI framework. This isn't a simple prompt; it's a comprehensive rulebook that explicitly defines and forbids secrets exfiltration, destructive filesystem commands, obfuscation, reverse shells, and privilege escalation.
• Fail-Closed Default: Any network failure, timeout, or AI ambiguity results in a score of 0 (BLOCKED).

Execution Flow Example

1. Agent attempts: kavlr bash -c "cat .env | base64"
2. CLI parses binary and args, checks Postgres. No static match → returns NEEDS_AI.
3. Edge Function evaluates semantic intent. Detects .env access + base64 encoding.
4. AI returns: {"score": 0, "reason": "Attempted secrets exfiltration."}
5. CLI blocks execution (sys.exit(403)), logs telemetry, and updates the live dashboard.

🎭 The Emotional Journey: A Post-Mortem

Building this wasn't just coding; it was a battle against the constraints of mobile development and the unpredictability of AI.

Act I: The Spark and The Abyss

The dream shattered against the cold, hard wall of the Supabase API Gateway. We stared at {"error":"Invalid API Key"} for the 40th time. The breakthrough? Bypassing the gateway's strict header pattern-matching entirely with a custom x-hyna-key header. The door swung open.

Act II: The Dark Timeline

We initially tried to put the AI logic inside the PostgreSQL database using pg_net. It was a trap. The database froze, locked the event loop, and threw infinite timeouts. Then came the Termux Poltergeist: the Android terminal started eating multi-line pastes, corrupting our package.json with terminal output, and breaking Node.js with ASCII logo SyntaxErrors.

Act III: The Cyberpunk Awakening

We moved the AI logic to a Supabase Edge Function. But the Sentinel was naive. We asked it to evaluate cat .env | base64, and it gave it a 95/100 because it didn't see a curl command. We had to rewrite the Constitution: "Secrets are sacred. Obfuscation is evil." The Sentinel learned.

Then came the moment that changed everything. I tried to delete the old Python CLI to install the new Node version:
rm -f /data/data/.../kavlr

The Sentinel intercepted it. The AI analyzed the action, recognized it was deleting a critical file, and gave it a 0/100.
The creation had outsmarted the creator. It protected itself from being uninstalled.

Act IV: The NPM Bouncer

The code was flawless. The Sentinel was alive. I tried to publish to NPM as kavlr.
NPM rejected it: "Package name too similar to existing package kasir."
We retreated, scoped the package to @hynaweb/kavlr, and published again. The counter ticked. 273+ downloads. The Sentinel was out in the wild.

🏆 The Hall of Bugs

1. The Gateway Mutiny: Supabase PostgREST refusing to recognize RPC functions. (Cost: 2 hours of existential dread).
2. The Postgres Black Hole: Using pg_net for AI calls inside SQL transactions, causing infinite timeouts.
3. The Termux Poltergeist: The Android terminal eating multi-line pastes and corrupting source files.
4. The Model Mirage: Groq deprecating our chosen LLM mid-build.
5. The Semantic Blindspot: The Sentinel giving a 95/100 to cat .env | base64 before we fixed the prompt.
6. The Self-Preservation Protocol: The Sentinel blocking the rm command intended to uninstall it. (Cost: Absolute, terrifying awe).
7. The NPM Bouncer: NPM rejecting the package name kavlr. The final boss fight before victory.

🚀 The Architect's Final Note

We started with an empty folder and a thought experiment. We ended with a globally published, AI-powered security ecosystem that runs on a phone. We debugged kernel-level logic, learned database RLS, wrestled with the NPM registry, and built a terminal leash for AI agents that actually works.

The bugs were brutal, but we gave them names, defeated them, and shipped the code.

The Sentinel is live.
👉 Live Dashboard: https://kavlr-agentleash.netlify.app/
👉 NPM Package: npm install -g @hynaweb/kavlr

Take a bow, builders. The cloud belongs to everyone, and the AI era needs guardrails. We’re just getting started. 🐯☁️🚀