Faramesh: AI Governance and AI Agent Execution Control

Pre-execution governance engine for AI agents.
One binary. Real governance workflow. 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
Setup Lifecycle (Source Checkout)
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
Corpus Contracts and CI Gates
Repository Map
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

# Homebrew
brew install faramesh/tap/faramesh

# Local installer script from repository checkout
./install.sh

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

# npm package
npx @faramesh/cli@latest setup flow

# Released from GitHub Actions via npm trusted publishing (OIDC); no long-lived npm publish token is needed.

# Source checkout (single setup entrypoint)
make setup

Setup Lifecycle (Source Checkout)

For local repositories and existing agent stacks (LangChain, LangGraph, DeepAgents, MCP), start from the guided product flow:

# Canonical setup command (guided first-run wizard)
faramesh wizard first-run

Key lifecycle commands:

# Guided first-run setup
faramesh wizard first-run

# Runtime controls
faramesh up --policy policies/default.fpl
faramesh run --broker -- python my_agent.py
faramesh approvals
faramesh explain <action-id>
faramesh audit tail
faramesh down

# Optional explicit credential setup
faramesh credential enable --policy policies/default.fpl

# Detach wiring from an existing project
faramesh offboard --path /path/to/agent
faramesh offboard --path /path/to/agent --apply

# Full cleanup: detach + remove local state
faramesh setup uninstall --path /path/to/agent --yes

# Binary maintenance
faramesh setup update
faramesh setup upgrade --version 0.5.0

Quick Start

Start here for real usage in a new or existing agent project:

Discover likely tool surfaces in your codebase.

faramesh discover

Attach Faramesh in shadow mode to collect runtime inventory without blocking traffic.

faramesh attach

Check what is covered and what is still missing.

faramesh coverage
faramesh gaps

Generate a starter policy from what was observed.

faramesh suggest --out suggested-policy.yaml

Run your actual agent under governance enforcement.

faramesh run --broker -- python agent.py

Move to managed pack lifecycle once baseline governance looks clean.

faramesh pack search
faramesh pack install <pack-ref> --mode shadow
faramesh pack status <pack-ref>
faramesh pack enforce <pack-ref>

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 --broker -- 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 --broker --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 --broker -- 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.

MCP docs are split by audience:

Fast setup and daily usage: MCP_INTERCEPTION_GOVERNANCE_PLAN.md
Full technical spec and deep hardening details: MCP_INTERCEPTION_GOVERNANCE_SPEC.md

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) Configure global credential sequestration defaults
faramesh credential enable --policy policies/payment-bot.fpl

# 2) Start runtime with persisted credential profile
faramesh up --policy policies/payment-bot.fpl

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

Advanced operator path: pass explicit backend and provider mappings only when your environment needs manual routing controls.

External Vault Integration

faramesh credential enable \
  --policy policies/payment-bot.fpl \
  --backend vault \
  --vault-addr https://vault.company.internal:8200 \
  --vault-token "$VAULT_TOKEN"

Use faramesh credential status to verify global backend/routing 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 identity status shows identity readiness (whoami, trust level, verify) in one command.
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 + credential broker + auto-patch (eBPF LSM scaffolded, not active)	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

Faramesh ships policy packs and a full lifecycle command surface.

Core usage:

faramesh pack search
faramesh pack preview <pack-ref>
faramesh pack install <pack-ref> --mode shadow
faramesh pack status <pack-ref>
faramesh pack enforce <pack-ref>
faramesh pack diff <pack-ref>
faramesh pack upgrade <pack-ref>

Bundled pack families in this repository:

Foundation packs: faramesh-starter, faramesh-coding-agent, faramesh-payment-agent, faramesh-support-agent, faramesh-mcp-server, faramesh-shell-controls, faramesh-infra-agent.
P2 vertical packs: faramesh-p2-data-agent, faramesh-p2-docs-writer, faramesh-p2-marketing-agent, faramesh-p2-email-outbound, faramesh-p2-customer-success, faramesh-p2-network-controls, faramesh-p2-ops-release, faramesh-p2-research-agent, faramesh-p2-vendor-diligence, faramesh-p2-webhook-agent, faramesh-p2-multi-agent.

Pack artifacts are written as policy.yaml with optional authored policy.fpl and normalized policy.compiled.yaml where available.

Pack authoring and validation

make packs-verify

This validates all on-disk pack policies and compiles bundled FPL sidecars.

Corpus Contracts and CI Gates

Faramesh release hardening is anchored by the corpus contract + matrix workflows under tests/corpus.

Local commands:

make corpus-contract
make corpus-matrix
make corpus-check
make corpus-run ENTRY=tests/corpus/framework-hooks/langchain-governed-smoke

This keeps release gating tied to real runnable harnesses and prevents stale matrix drift.

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

CLI Reference

See the full CLI reference for full command documentation.

The public Faramesh help surface is tiered:

Core commands: default product path for day-1 usage and everyday governance.
Operator commands: powerful operational workflows for onboarding, incident response, approvals, and runtime control.
Advanced commands: expert and multi-system workflows.
Internal commands: engineering-only surfaces, intentionally hidden from help.

Core Top-Level Commands (Visible)

Command	Primary role
`faramesh up`	Start the product stack (runtime + visibility + approvals UI when available)
`faramesh down`	Stop the product stack cleanly
`faramesh status`	Show daemon and runtime health
`faramesh run -- <cmd>`	Run an agent process under governance enforcement
`faramesh approvals`	List, approve, deny, and open approvals UI
`faramesh policy`	Validate, compile, and test policies
`faramesh audit`	Tail, verify, inspect, and export evidence
`faramesh auth`	Login/logout/status for platform auth
`faramesh credential`	Broker and vault credential lifecycle
`faramesh wizard`	Guided first-run and enterprise setup flow

Operator Top-Level Commands (Visible)

Command	Primary role
`faramesh start`	Start runtime-only process (operator compatibility path)
`faramesh stop`	Stop runtime-only process
`faramesh serve`	Run daemon directly with explicit runtime options
`faramesh setup`	Guided setup and lifecycle management
`faramesh onboard`	Onboarding readiness checks and bootstrap guidance
`faramesh offboard`	Remove Faramesh runtime wiring from projects
`faramesh discover`	Find likely governance surfaces in a project
`faramesh attach`	Attach in observe-first mode
`faramesh coverage`	Report static/runtime governance coverage
`faramesh gaps`	Report uncovered governance surfaces
`faramesh suggest`	Generate starter policy from observed inventory
`faramesh agent`	Agent control workflows (pending/history/kill/unkill)
`faramesh identity`	Workload and agent identity controls
`faramesh incident`	Incident declaration/isolation workflows
`faramesh provenance`	Provenance attestations and drift checks
`faramesh pack`	Search/install/manage policy packs
`faramesh mcp`	Wrap MCP servers with governance

Advanced Top-Level Commands (Visible)

Command	Primary role
`faramesh detect`	Detect local framework/runtime characteristics
`faramesh init`	Scaffold baseline Faramesh files in a project
`faramesh explain`	Explain a decision record in detail
`faramesh compliance`	Compliance evidence workflows (`export`, `resign`)
`faramesh key`	Runtime signing key inspection/export
`faramesh fleet`	Multi-instance fleet operations
`faramesh delegate`	Agent-to-agent delegation chains
`faramesh federation`	Cross-organization federation and trust relationships
`faramesh schedule`	Scheduled tool execution workflows

Internal Top-Level Commands (Hidden)

chaos-test, compensate, demo, hub, model, ops, sbom, session, sign, verify

Operator note: set faramesh serve --dpr-hmac-key <secret> from stable secret storage in production. DPR records are signed with Ed25519 (persisted keypair in runtime data dir), while HMAC is still used for approval-envelope integrity and compatibility paths.

Migration note: faramesh compliance resign supports dry-run/apply backfill of Ed25519 signatures for historical records after enabling canonicalized signing in a live environment.

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-sdk`
TypeScript / Node.js	`sdk/node`	`npm install @faramesh/sdk`

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:

Quick-user docs first:

Power-user docs:

More docs and references:

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

Mozilla Public License 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 212 Commits
.github		.github
Formula		Formula
cmd		cmd
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
faramesh-core-logo.svg		faramesh-core-logo.svg
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

Pack authoring and validation

Corpus Contracts and CI Gates

Repository Map

CLI Reference

Core Top-Level Commands (Visible)

Operator Top-Level Commands (Visible)

Advanced Top-Level Commands (Visible)

Internal Top-Level Commands (Hidden)

Architecture

SDKs

Documentation

Community

Contributing

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`deny!` — mandatory deny