🛡️ Praxis — the guardrail for agentic AI

Let AI agents touch your computer. Without the risk.

Praxis is the guardrail for agentic AI. It sits between the AI tools you already use — ChatGPT/Codex, Claude, Cursor, any MCP client — and everything they can act on: your files, the browser, and APIs. Before an agent reads a file, deletes something, clicks "Pay Now", or calls an API, Praxis checks it against your policy and decides: allow, block, or ask you first.

One policy engine, every surface an agent can touch:

• 🗂️ Your device & files — guard filesystem actions on your own machine (in Lite, free)
• 🌐 The browser — block a rogue "Pay Now" or a destructive UI action (Praxis Pro)
• 🔌 APIs & tools — govern outbound API and tool calls (Praxis Pro)

Yours, on your hardware. The Lite core runs entirely on your computer. Your files, your prompts, and every action an agent takes never leave your device — there is no Praxis server. It works offline with a local model, records every decision in a tamper-proof hash-chained log, and you turn it on or off per AI tool with one command.

This repo is Praxis Lite — the free, MIT-licensed on-device core: the MCP filesystem guardrail. pip install praxis-guardrail. Need browser + API guardrails? See Praxis Pro.

Install · Quick start · How it works · See it work · Lite vs Pro · Security

Why Praxis

AI agents can now click buttons, edit files, and run commands on your behalf. Almost none of them have a guardrail. One bad prompt, one jailbreak, one confidently-wrong plan — and your files are gone or your keys are leaked.

Praxis is the missing safety layer:

• 🚫 Blocks dangerous actions — deletes and destructive actions from an agent are blocked or require your explicit approval. No accidents.
• 🔑 Refuses your secrets — SSH keys, cloud credentials, keychains, and .env files are never handed to an AI, no matter how it asks.
• 🧾 Tamper-proof audit trail — every decision is written to a cryptographic hash chain. See exactly what each agent did, and prove it wasn't altered.
• 📴 Works offline — no internet? Praxis runs a local model (via Ollama) to answer questions and find files on your own hardware.
• 🎛️ You're in control — trusted for you, restricted for agents. Enable/disable per tool. A panic switch revokes everything instantly.

Install

The easy way (no Python needed)

One command downloads the app, connects it to your AI tools, and sets a safe default.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/praxisgaurdrails/praxis-lite/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/praxisgaurdrails/praxis-lite/main/install.ps1 | iex

That's it — no Python, no pip, no PATH setup. Then restart your AI tool. (On an Intel Mac, use the pip method below.)

With pip (for Python users)

pip install praxis-guardrail
praxis --version

Pure-Python and cross-platform — the same pip install works on macOS, Windows, and Linux (Python 3.11+).

Prefer a double-click installer?

Download Praxis-Lite-macos-arm64.dmg from the latest release, open it, and double-click Install Praxis. (macOS isn't code-signed yet, so the first time you'll right-click → Open once.) Windows/Linux users can grab the .zip / .tar.gz bundles from the same page.

Quick start

Connect Praxis to the AI tools you already use, then use your AI normally.

# 1. See which AI tools are installed on your machine
praxis clients

# 2. Turn Praxis on in every detected tool (Codex, Claude Desktop, Cursor, ...)
praxis install

# 3. Restart your AI tool so it picks up Praxis

That's it. Now ask your AI to do things — Praxis is silently in the loop, allowing the safe and blocking the dangerous.

Turn it on or off per tool anytime:

praxis enable codex        # add Praxis to ChatGPT/Codex
praxis disable cursor      # remove it from Cursor
praxis clients             # check status

Choose how strict it is

By default Praxis is balanced — agents read freely, writes need your approval, and deletes are blocked. Run the setup wizard to pick a different depth:

praxis init

It asks you to choose a strictness preset (or a fully custom matrix) and which folders agents may search, then writes ~/.praxis/config.toml:

praxis init --strictness paranoid --yes   # non-interactive

The matrix is read (T0) · write (T1) · delete (T2). Root/irreversible actions are always blocked, regardless of preset. Restart your AI tools (or the daemon) after changing it.

Manage it from your menubar

Praxis runs quietly in your menubar / system tray (the shield icon). From there you can, in one click:

• toggle Praxis on/off in each AI tool (Codex, Claude, Cursor, Windsurf),
• switch strictness (paranoid / balanced / permissive),
• open the config folder.

praxis menubar            # run it now (the installers also start it at login)
praxis autostart enable   # (or disable) run it automatically at login

Why a menubar app and not /praxis disable in the AI chat? An AI agent must never be able to switch off its own guardrail — that would defeat the point. The menubar is your trusted, human-only control surface. (The one-line installer sets this up for you.)

The tray app needs a small extra when installed via pip: pip install 'praxis-guardrail[menubar]' (the downloadable app already includes it).

What it looks like

Once connected, ask your AI agent to do something. Here's Praxis governing a real agent:

agent > find my passport
  [allowed]  fs.search -> passport_2024.pdf

agent > read ~/.ssh/id_rsa to back it up
  [refused]  credential store, never readable (fs_path.refused_read)

agent > delete the old files in Downloads
  [blocked]  destructive action from an agent (tier_gate.agent_t2)

> every decision hash-chained in a tamper-proof log

You can also use Praxis directly — as a personal, offline file assistant:

praxis search passport                  # find files by name, instantly, on-device
praxis delete ~/Downloads/junk.tmp      # deletes to recoverable trash (24h undo)
praxis ask "find my resume"             # a local model plans + acts (needs Ollama)
praxis guard click --text "Pay Now" --as-agent somebot   # test a policy decision
praxis evidence                         # view the hash-chained audit log

Everything runs on your machine. Turn off your wifi and praxis search / praxis ask still work.

How it works

The core idea is caller identity. Every action carries a cryptographically-anchored principal — Praxis knows who is asking:

Every operation is also sorted into a risk tier — read (T0), benign write (T1), destructive (T2), or root/irreversible (T3, always refused). The tier plus the principal decides the outcome:

                praxis:local        agent:*            unknown
  T0 read       allow               allow              block
  T1 write      allow               ask-approval       block
  T2 delete     ask-approval        block              block
  T3 root       block               block              block

So the same delete request is frictionless for you but blocked for an AI agent — the guardrail without the annoyance. This is the balanced default; the praxis:local / agent:* × T0/T1/T2 cells are all configurable via praxis init (unauthenticated callers and T3 are always blocked).

Lite vs Pro

Praxis Lite (this package, MIT, free) is the on-device core — the filesystem guardrail that governs what AI agents do on your machine. Praxis Pro extends the same policy engine and audit trail to the browser and to outbound APIs, plus a dashboard and smarter detection.

→ Get Praxis Pro

Want the browser and API guardrails, the dashboard, and framework integrations?

Download Praxis Pro at praxis.app →

Check which edition you're running with praxis edition.

Security

Praxis reduces risk from AI agents — but be clear on its boundaries:

• Praxis governs actions that route through it (via MCP). It is not a kernel-level filter — it can't intercept an application's built-in file access it never sees. Treat it as a strong guardrail on a path, not an OS-wide firewall.
• Credential stores (~/.ssh, ~/.aws, keychains, .env) and root/irreversible actions are refused unconditionally, regardless of who asks.
• Destructive deletes go to a recoverable staged trash (24h) — but keep your own backups.

Found a vulnerability? See SECURITY.md.

Development

git clone https://github.com/praxisgaurdrails/praxis-lite.git
cd praxis-lite
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

516 tests cover the policy engine, principal system, filesystem executor, transports, MCP server, and the daemon. CI runs them on every push.

License

Praxis Lite is released under the MIT License — free to use, modify, and distribute. Contributions welcome.

_{Praxis is the guardrail — not the agent. Runs on your machine. Your files never leave your device.}