Faramesh: AI Governance and AI Agent Execution Control

Pre-execution governance engine for AI agents.
One binary. One command. Every framework.

Faramesh: AI Governance and AI Agent Execution Control

Faramesh is a deterministic AI governance engine for AI agents and tool-calling systems. It enforces execution control before actions run, adds human approval when needed, and writes tamper-evident decision evidence for audit and compliance.

_{Governance demo view: policy, enforcement, and runtime workflow at a glance.}

Contents

Faramesh: AI Governance and AI Agent Execution Control
What is Faramesh?
Install
Quick Start
FPL - Faramesh Policy Language
Supported Frameworks
Use Cases
Governing Real Runtimes
Credential Broker
Workload Identity (SPIFFE/SPIRE)
Observability Integrations
Latency Benchmarks
Cross-Platform Enforcement
Policy Packs
Repository Map
Documentation Hub
CLI Reference
Architecture
SDKs
Documentation
Community
Contributing
License

What is Faramesh?

Faramesh sits between your AI agent and the tools it calls. Every tool call is checked against your policy before it runs. If the policy says no, the action is blocked. If the policy says wait, a human decides. Every decision is logged to a tamper-evident chain.

Most "AI governance" tools add a second AI to watch the first. That's probability watching probability. Faramesh uses deterministic rules — code that evaluates the same way every time. No model in the middle. No guessing.

Install

# curl (fastest)
curl -fsSL https://raw.githubusercontent.com/faramesh/faramesh-core/main/install.sh | bash

# Homebrew
brew install faramesh/tap/faramesh

# npm package
npx @faramesh/cli@latest init

# Go toolchain
go install github.com/faramesh/faramesh-core/cmd/faramesh@latest

# Source checkout (single setup entrypoint)
make setup

Setup Lifecycle (Source Checkout)

For local repositories and existing agent stacks (LangChain, LangGraph, DeepAgents, MCP), use one command surface:

# Canonical setup command
bash scripts/faramesh_setup.sh

Key lifecycle commands:

# Guided governance startup (framework + policy + credential profile toggles)
bash scripts/faramesh_setup.sh start

# Optional preflight only
bash scripts/faramesh_setup.sh onboard --policy policies/default.fpl

# Stop / inspect runtime
bash scripts/faramesh_setup.sh status
bash scripts/faramesh_setup.sh stop

# Detach Faramesh wiring from an existing project (dry-run, then apply)
bash scripts/faramesh_setup.sh offboard --path /path/to/agent
bash scripts/faramesh_setup.sh offboard --path /path/to/agent --apply

# Full cleanup: detach + remove local runtime and common local binaries
bash scripts/faramesh_setup.sh uninstall --path /path/to/agent --yes

Quick Start

# Govern your agent — one command
faramesh run -- python agent.py

Faramesh Enforcement Report
  Runtime:     local
  Framework:   langchain

  ✓ Framework auto-patch (FARAMESH_AUTOLOAD)
  ✓ Credential broker (stripped: OPENAI_API_KEY, STRIPE_API_KEY)
  ✓ Network interception (proxy env vars)

  Trust level: PARTIAL

Watch live decisions:

faramesh audit tail

[10:00:15] PERMIT  get_exchange_rate      from=USD to=SEK              latency=11ms
[10:00:17] DENY    shell/run              cmd="rm -rf /"               policy=deny!
[10:00:18] PERMIT  read_customer          id=cust_abc123               latency=9ms
[10:00:20] DEFER   stripe/refund          amount=$12,000               awaiting approval
[10:00:21] DENY    send_email             recipients=847               policy=deny-mass-email

FPL — Faramesh Policy Language

FPL is the standard policy language for Faramesh. Every policy starts as FPL. It is a domain-specific language purpose-built for AI agent governance — shorter than YAML, safer than Rego, readable by anyone.

agent payment-bot {
  default deny
  model "gpt-4o"
  framework "langgraph"

  budget session {
    max $500
    daily $2000
    max_calls 100
    on_exceed deny
  }

  phase intake {
    permit read_customer
    permit get_order
  }

  rules {
    deny! shell/* reason: "never shell"
    defer stripe/refund when amount > 500
      notify: "finance"
      reason: "high value refund"
    permit stripe/* when amount <= 500
  }

  credential stripe {
    backend vault
    path secret/data/stripe/live
    ttl 15m
  }
}

Why FPL?

	FPL	YAML + expr	OPA / Rego	Cedar
Agent-native primitives	Yes — sessions, budgets, phases, delegation, ambient	Convention-based	No	No
Mandatory deny (`deny!`)	Compile-time enforced	Documentation convention	Runtime only	Runtime only
Lines for above policy	25	65+	80+	50+
Natural language compilation	Yes	No	No	No
Backtest before activation	Built-in	Manual	Manual	No

Multiple input modes, one engine

FPL is the canonical format. You can also write policies as:

Natural language — faramesh policy compile "deny all shell commands, defer refunds over $500 to finance" compiles to FPL, validates it, and backtests it against real history before activation.
YAML — always supported as an interchange format. faramesh policy compile policy.yaml --to fpl converts to FPL. Both formats compile to the same internal representation.
Code annotations — @faramesh.tool(defer_above=500) in your source code is extracted to FPL automatically.

`deny!` — mandatory deny

deny! is a compile-time constraint. It cannot be overridden by position, by a child policy in an extends chain, by priority, or by any subsequent permit rule. OPA, Cedar, and YAML-based engines express this as a documentation convention. FPL enforces it structurally.

Supported Frameworks

All 13 frameworks are auto-patched at runtime — zero code changes required.

Framework	Patch Point
LangGraph / LangChain	`BaseTool.run()`
CrewAI	`BaseTool._run()`
AutoGen / AG2	`ConversableAgent._execute_tool_call()`
Pydantic AI	`Tool.run()` + `Agent._call_tool()`
Google ADK	`FunctionTool.call()`
LlamaIndex	`FunctionTool.call()` / `BaseTool.call()`
AWS Strands Agents	`Agent._run_tool()`
OpenAI Agents SDK	`FunctionTool.on_invoke_tool()`
Smolagents	`Tool.__call__()`
Haystack	`Pipeline.run()`
Deep Agents	LangGraph dispatch + `AgentMiddleware`
AWS Bedrock AgentCore	App middleware + Strands hook
MCP Servers (Node.js)	`tools/call` handler

Use Cases

AI governance for production agent systems where every tool call must be policy-checked.
AI agent guardrails for coding agents, customer support agents, and payment workflows.
AI execution control for MCP tools, API actions, shell actions, and delegated sub-agents.
Compliance-ready decision evidence with deterministic replay and tamper-evident provenance.

Governing Real Runtimes

OpenClaw

faramesh run -- node openclaw/gateway.js

Faramesh patches the OpenClaw tool dispatch, strips credentials from ~/.openclaw/, and governs every tool call through the policy engine. The agent never sees raw API keys.

NemoClaw

faramesh run --enforce full -- python -m nemoclaw.serve --config agent.yaml

NemoClaw runs inside Faramesh's sandbox. On Linux, the kernel sandbox (seccomp-BPF, Landlock, network namespace) prevents the agent from bypassing governance.

Deep Agents (LangChain)

faramesh run -- python -m deep_agents.main

Faramesh patches BaseTool.run() and injects AgentMiddleware into the LangGraph execution loop. Multi-agent delegation is tracked with cryptographic tokens — the supervisor's permissions are the ceiling for any sub-agent.

Claude Code / Cursor

faramesh mcp wrap -- node your-mcp-server.js

Faramesh intercepts every MCP tools/call request. The IDE agent connects to Faramesh instead of the real MCP server. Non-tool-call methods pass through unchanged.

Credential Broker

Faramesh strips API keys from the agent's environment. Credentials are only issued after the policy permits the specific tool call.

Backend	Config
HashiCorp Vault	`--vault-addr`, `--vault-token`
AWS Secrets Manager	`--aws-secrets-region`
GCP Secret Manager	`--gcp-secrets-project`
Azure Key Vault	`--azure-vault-url`, `--azure-tenant-id`
1Password Connect	`FARAMESH_CREDENTIAL_1PASSWORD_HOST`
Infisical	`FARAMESH_CREDENTIAL_INFISICAL_HOST`

Local Vault Provisioning + Interactive Key Intake

For hard boundary local development, Faramesh can provision a local Vault dev instance and securely prompt for a key so it is written directly to brokered Vault storage.

# 1) Provision local Vault (writes state under ~/.faramesh/local-vault)
faramesh credential vault up

# 2) Prompt for key and store it at secret/data/faramesh/stripe/refund
faramesh credential vault put stripe/refund

# 3) Start daemon with Vault broker backend
source ~/.faramesh/local-vault/vault.env
faramesh serve \
  --policy policies/payment-bot.fpl \
  --vault-addr "$FARAMESH_CREDENTIAL_VAULT_ADDR" \
  --vault-token "$FARAMESH_CREDENTIAL_VAULT_TOKEN" \
  --vault-mount secret

# 4) Run agent with ambient secret stripping
faramesh run --broker --agent-id payment-bot -- python your_agent.py

External Vault Integration

faramesh credential vault put stripe/refund \
  --external \
  --vault-addr https://vault.company.internal:8200 \
  --vault-token "$VAULT_TOKEN" \
  --vault-mount secret

Use faramesh credential vault status to verify health and faramesh credential vault down to stop locally provisioned dev Vault.

Workload Identity (SPIFFE/SPIRE)

Faramesh can consume SPIFFE workload identity at runtime and expose identity controls in the CLI.

faramesh serve --spiffe-socket <path> enables SPIFFE workload identity resolution from the Workload API socket.
faramesh identity verify --spiffe spiffe://example.org/agent verifies workload identity state.
faramesh identity trust --domain example.org --bundle /path/to/bundle.pem configures trust domain and bundle.

In a SPIRE-based deployment, CA issuance and SVID lifecycle management are handled by SPIRE/SPIFFE components. Faramesh consumes the resulting SPIFFE identity and trust data for policy decisions and credential brokering.

Observability Integrations

Faramesh exposes Prometheus-compatible metrics on /metrics via --metrics-port. This is the integration point for common observability platforms:

Grafana: scrape via Prometheus or Grafana Alloy, then build dashboards and alerts.
Datadog: use OpenMetrics scraping against /metrics and correlate with decision/audit events.
New Relic: ingest Prometheus/OpenMetrics data from /metrics for governance and runtime monitoring.

Latency Benchmarks

Faramesh includes a reproducible benchmark target for policy-engine and full-pipeline latency:

make benchmark-latency

Command details used for the numbers below:

go test ./internal/core/policy -run '^$' -bench BenchmarkEngineEvaluateSimplePermit -benchmem -benchtime=2s -cpu=1 -count=5
go test ./internal/core -run '^$' -bench BenchmarkPipelineEvaluateSimplePermit -benchmem -benchtime=2s -cpu=1 -count=5

Measured on 2026-04-06 (darwin/arm64, Apple M1):

Benchmark	Median Latency	Allocations
`BenchmarkEngineEvaluateSimplePermit`	`68.52 ns/op`	`0 allocs/op`
`BenchmarkPipelineEvaluateSimplePermit`	`57,774 ns/op` (`57.774 us/op`)	`151 allocs/op`

Observed added latency for full governance pipeline vs raw policy evaluation:

approximately 57.705 us per decision on median samples.

These are reference measurements for release engineering, not hard latency guarantees.

Cross-Platform Enforcement

Platform	Layers	Trust Level
Linux + root	seccomp-BPF + Landlock + netns + eBPF + credential broker + auto-patch	STRONG
Linux	Landlock + proxy + credential broker + auto-patch	MODERATE
macOS	Proxy env vars + PF rules + credential broker + auto-patch	PARTIAL
Windows	Proxy env vars + WinDivert + credential broker + auto-patch	PARTIAL
Serverless	Credential broker + auto-patch	CREDENTIAL_ONLY

Policy Packs

Ready-to-use FPL policies in examples/:

File	Description
`starter.fpl`	General-purpose starter policy — blocks destructive commands, defers large payments
`payment-bot.fpl`	Financial agent with session budgets, phased workflow, and credential brokering
`infra-bot.fpl`	Infrastructure agent with strict sandbox, Terraform governance, and duty delegation
`customer-support.fpl`	Support agent with intake/resolve phases, credit limits, and mass-email protection
`mcp-server.fpl`	MCP server wrapper policy for IDE agents (Claude Code, Cursor)

Repository Map

faramesh-core/
├── cmd/                  # CLI entrypoints
├── internal/             # Governance engine, adapters, policy runtime
├── sdk/                  # Official SDKs (Node, Python)
├── deploy/               # Kubernetes, ECS, Nomad, systemd, Cloud Run examples
├── examples/             # Ready-to-run FPL policy examples
├── packs/                # Policy packs
└── docs/                 # Product and architecture documentation

Documentation Hub

CLI Reference

See the full CLI reference for all 30+ commands. Key commands:

Command	What it does
`faramesh run -- <cmd>`	Govern an agent with the full enforcement stack
`faramesh policy validate <path>`	Validate an FPL or YAML policy
`faramesh policy compile <text>`	Compile natural language to FPL
`faramesh audit tail`	Stream live decisions
`faramesh audit verify`	Verify DPR chain integrity
`faramesh agent approve <token>`	Approve a deferred action
`faramesh agent kill <id>`	Emergency kill switch
`faramesh credential register <name>`	Register a credential with the broker
`faramesh credential vault up`	Provision local dev Vault for brokered secrets
`faramesh credential vault put <tool-id>`	Prompt for key and store at broker Vault path
`faramesh credential vault status`	Check Vault health and local provisioning state
`faramesh credential vault down`	Stop local dev Vault provisioned by Faramesh
`faramesh session open`	Open a governance session
`faramesh offboard --path <dir>`	Automatically remove Faramesh runtime wiring from agent code (dry-run by default)
`faramesh incident declare <desc>`	Declare a governance incident
`faramesh mcp wrap <server>`	Wrap an MCP server with governance

Architecture

flowchart TB
    subgraph agentProc ["Agent Process"]
        FW["Framework Dispatch"]
        AP["Auto-Patch Layer"]
        SDK["Faramesh SDK"]
    end

    subgraph kernelEnf ["Kernel Enforcement"]
        SECCOMP["seccomp-BPF"]
        EBPF["eBPF Probes"]
        LANDLOCK["Landlock LSM"]
        NETNS["Network Namespace"]
    end

    subgraph daemonProc ["Faramesh Daemon — 11-Step Pipeline"]
        KILL["1. Kill Switch"]
        PHASE["2. Phase Check"]
        SCAN["3. Pre-Scanners"]
        SESS["4. Session State"]
        HIST["5. History Ring"]
        SEL["6. Selectors"]
        POLICY["7. Policy Engine"]
        DEC["8. Decision"]
        WAL_W["9. WAL Write"]
        ASYNC["10. Async DPR"]
        RET["11. Return"]
    end

    subgraph credPlane ["Credential Plane"]
        BROKER["Credential Broker"]
        VAULT["Vault / AWS / GCP / Azure / 1Pass / Infisical"]
    end

    FW --> AP --> SDK
    SDK -->|"Unix socket"| KILL --> PHASE --> SCAN --> SESS --> HIST --> SEL --> POLICY --> DEC --> WAL_W --> ASYNC --> RET
    DEC -->|PERMIT| BROKER --> VAULT
    DEC -->|DENY| RET
    DEC -->|DEFER| HUMAN["Human Approver"]
    EBPF -.->|"syscall monitor"| agentProc
    SECCOMP -.->|"immutable filter"| agentProc
    NETNS -.->|"traffic redirect"| daemonProc

If the WAL write fails, the decision is DENY. No execution without a durable audit record.

SDKs

Language	Path	Package
Python	`sdk/python`	`pip install faramesh`
TypeScript / Node.js	`sdk/node`	`npm install faramesh`

Both SDKs provide govern(), GovernedTool, policy helpers, snapshot canonicalization, and gate() for wrapping any tool call with pre-execution governance.

Documentation

Full documentation at faramesh.dev/docs.

Repository docs for crawlers and contributors:

Search Topics (SEO)

This repository targets high-intent technical topics across agent governance and runtime control:

AI governance
AI agent governance
AI agent security
AI execution control
Agent execution control
Policy as code for AI agents
Deterministic policy engine
MCP governance and Model Context Protocol guardrails
AI compliance and agent audit trail

Community

Help shape Faramesh and track what is next:

Contribution guidelines: CONTRIBUTING.md
Roadmap and milestones: GitHub Milestones
Roadmap discussions/issues: Roadmap-labeled issues

Contributing

See CONTRIBUTING.md for development setup, coding standards, and contribution workflow.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 146 Commits
.github		.github
Formula		Formula
cmd/faramesh		cmd/faramesh
deploy		deploy
docs		docs
examples		examples
internal		internal
npm		npm
packs		packs
policies		policies
scripts		scripts
sdk		sdk
tests		tests
visibility-server		visibility-server
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
faramesh		faramesh
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

Faramesh: AI Governance and AI Agent Execution Control

What is Faramesh?

Install

Setup Lifecycle (Source Checkout)

Quick Start

FPL — Faramesh Policy Language

Why FPL?

Multiple input modes, one engine

deny! — mandatory deny

Supported Frameworks

Use Cases

Governing Real Runtimes

OpenClaw

NemoClaw

Deep Agents (LangChain)

Claude Code / Cursor

Credential Broker

Local Vault Provisioning + Interactive Key Intake

External Vault Integration

Workload Identity (SPIFFE/SPIRE)

Observability Integrations

Latency Benchmarks

Cross-Platform Enforcement

Policy Packs

Repository Map

Documentation Hub

CLI Reference

Architecture

SDKs

Documentation

Community

Contributing

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`deny!` — mandatory deny