Faramesh：首個用於 AI 代理的確定性執行控制平面

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

To see all available qualifiers, see our documentation.

faramesh-core

License

Uh oh!

There was an error while loading. Please reload this page.

faramesh/faramesh-core

Folders and files

Latest commit

History

Repository files navigation

Faramesh

Execution gatekeeper for AI agents

Faramesh Core is an open-core execution governor that provides policy-driven governance, risk scoring, and human-in-the-loop approval for AI agent tool calls. Built for production use with a modern web UI, comprehensive CLI, and SDK integrations.

Faramesh Cloud Products

Faramesh Horizon (hosted control plane)

Faramesh Horizon is our fully-managed SaaS offering that provides instant onboarding with no deployments required. Horizon includes a fully-managed core service, automatic upgrades, usage tracking and metrics, API keys and secrets management, and approval routing via Slack and email. Ideal for startups and small teams who want to get started quickly without infrastructure management.

Faramesh Nexus (enterprise/on-prem)

Faramesh Nexus is an enterprise-grade deployment of Faramesh that runs inside your VPC or Kubernetes cluster. Nexus supports SSO, RBAC, multi-org management, audit exports with long-term retention, and optional air-gap compatibility for security-critical environments. Perfect for organizations that need full control over their governance infrastructure.

Faramesh OSS is the engine, Nexus and Horizon are the accelerators.

Features

🎯 Core Capabilities

🚀 Quick Start (TL;DR)

SDKs:

Note: Framework integrations work with just pip install faramesh - no SDK package needed!

See docs/Quickstart.md for a step‑by‑step guide.

Table of Contents

Installation

Prerequisites

Install from Source

Optional Dependencies

For enhanced CLI output and DX features:

This installs:

Note: All features work without these dependencies, with graceful fallbacks to plain text output.

Quick Start

1. Start the Server

Server starts on http://127.0.0.1:8000 by default.

2. Access the Web UI

Open http://127.0.0.1:8000 in your browser.

The UI provides:

3. Submit Your First Action

Python SDK:

Alternative (Class-based API):

cURL:

4. View Actions

CLI:

Web UI:

Core Concepts

Actions

An action represents a tool call that an AI agent wants to execute. Each action has:

Policy Evaluation

Policies are evaluated in order, and the first matching rule wins. If no rules match, the action is denied by default (deny-by-default security model).

Risk Scoring

Risk scoring runs independently of policy rules. Risk rules can trigger automatic approval requirements even if a policy rule would allow the action.

Policy Configuration

Policies are defined in YAML files. By default, Faramesh looks for policies/default.yaml.

Basic Policy Structure

Match Conditions

Available match conditions:

Policy Effects

Each rule can have one effect:

Example Policies

Block Destructive Shell Commands:

Require Approval for Large Payments:

Risk Scoring

Risk scoring provides an additional layer of safety by automatically assessing action risk levels.

Risk Rules

Define risk rules in your policy file:

Risk Levels

Risk Rule Matching

Risk rules use the same match conditions as policy rules. The first matching risk rule determines the risk level.

High-Risk Auto-Approval

If an action has risk_level: high and a policy rule would allow it, Faramesh automatically changes the decision to require_approval for safety.

CLI Usage

Faramesh provides a powerful CLI for managing actions and policies.

Basic Commands

DX Commands

Prefix Matching

All commands that take an action ID support prefix matching. Use the first 8+ characters:

If multiple actions match, Faramesh will warn you and list all matches.

Global Options

Command Examples

List actions with risk levels (color-coded):

Explain why action was allowed/denied:

View event timeline:

Stream live actions (SSE):

Get curl commands:

DX Commands:

Web UI

The Faramesh web UI provides a modern, real-time dashboard for monitoring and managing actions.

Features

Accessing the UI

UI Workflow

Event Timeline

The event timeline shows every state change:

Each event includes:

SDK Integration

Python SDK

Modern Functional API:

Class-based API (Legacy):

Node.js SDK

LangChain Integration

Faramesh provides a drop-in wrapper for LangChain tools that automatically enforces governance.

Basic Usage

Integration with Agents

How It Works

See examples/langchain/ for a complete runnable demo with HTTP and shell tools.

Docker Deployment

Quick Start

Custom Build

Docker Compose

The docker-compose.yaml includes:

Edit docker-compose.yaml to customize:

API Reference

Endpoints

Returns array of events:

Returns SSE stream of action updates.

Returns Prometheus metrics.

Environment Variables

Server Configuration

Policy & Database

Legacy Variables

These are still supported but FARAMESH_* variants take precedence:

Quick Reference

All configurable via environment variables:

Or use .env file:

Examples & Starter Kits

Quick Links

Example 1: Basic Agent Integration

Example 2: Policy with Risk Scoring

Example 3: Docker Compose with Custom Policy

Architecture

High‑level data flow:

Execution Gate Flow

The deterministic execution gate ensures all actions pass through canonicalization, profile evaluation, and policy evaluation before any execution occurs.

Decision Outcomes:

Version-Bound Fields: Every decision includes deterministic metadata: request_hash, policy_hash, profile_hash, runtime_version, and provenance_id for replay verification.

See also:

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

DX Features

Faramesh includes comprehensive developer experience features:

See docs/CLI.md and docs/Policies.md for complete DX and policy documentation.

Project Structure

License

Faramesh Core is made available under the Elastic License 2.0.

You are free to use, modify, and integrate Faramesh Core in your own products and services, except you may not offer it as a competing hosted service where the primary value is Faramesh Core itself.

Governance

Troubleshooting

Installation Issues

If installation fails, upgrade pip: python3 -m pip install --upgrade pip

Support

Built with ❤️ for safe AI agent operations

Architecture Diagrams

1. Core Runtime Flow

The primary execution path from agent action submission through policy evaluation to final execution and logging.

2. Policy Evaluation Layer

How YAML policies are loaded, matched against actions, and produce decisions.

3. Execution Decision Lifecycle

The complete lifecycle of an action from creation through approval, execution, and final audit logging.

4. Integration Surface

All integration points that connect to Faramesh Core and consume its outputs.

5. Deployment Topologies

Three common deployment patterns for Faramesh.

Single Binary (Local):

Docker Compose:

Kubernetes:

6. OSS vs Cloud Features

The open-source core and the hosted/enterprise feature layers.

7. Secure-by-Default Pattern

The security model ensuring no side effects occur until approval.

FAQ

What is Faramesh?

Faramesh is an execution gatekeeper for AI agents that intercepts tool calls before execution, evaluates them against configurable policies, requires human approval when necessary, and logs every decision for audit purposes.

How does Faramesh differ from other agent frameworks?

Faramesh focuses specifically on governance and safety—it doesn't build agents, it governs them. It provides policy-driven control, risk scoring, and human-in-the-loop approval workflows that work with any agent framework.

Do I need to modify my existing agents?

No. Faramesh integrates via SDKs that wrap your existing tools. Your agents call the SDK instead of tools directly, and Faramesh handles the governance layer transparently.

See Govern Your Own Tool for a step-by-step tutorial on wrapping custom tools.

What happens if Faramesh is down?

This depends on your integration pattern. The SDK can be configured to fail-open (allow actions) or fail-closed (deny actions) when Faramesh is unavailable. Production deployments should run Faramesh as a critical service with appropriate redundancy.

Can I use Faramesh in production?

Yes. Faramesh Core is production-ready with PostgreSQL support, comprehensive APIs, web UI, and robust error handling. For enterprise features like SSO, RBAC, and advanced routing, consider Faramesh Nexus or Horizon.

How do policies work?

Policies are YAML files that define rules evaluated in order (first-match-wins). Each rule can allow, deny, or require approval. If no rule matches, actions are denied by default (secure-by-default).

What's the difference between policy rules and risk scoring?

Policy rules determine the decision (allow/deny/require_approval). Risk scoring provides an independent assessment (low/medium/high) that can automatically upgrade decisions—for example, high-risk actions automatically require approval even if a policy would allow them.

Can I integrate with CI/CD pipelines?

Yes. Faramesh provides CLI tools and APIs that can be integrated into CI/CD workflows to govern automated actions and deployments.

Is there a hosted version?

Yes. Faramesh Horizon provides a fully-managed SaaS offering, and Faramesh Nexus provides enterprise on-prem deployments. See the Faramesh Cloud Products section above.

What databases are supported?

Faramesh supports SQLite (default, for development) and PostgreSQL (recommended for production). The database stores actions, events, and audit logs.

How do I handle approvals in automated workflows?

For automated workflows, you can configure policies to allow low-risk actions automatically while requiring approval for high-risk operations. You can also integrate with approval systems via the API or use Faramesh Nexus/Horizon for advanced routing.

Can I export audit logs?

Yes. All actions and events are stored in the database and can be exported via the API. Faramesh Nexus includes advanced audit export features with long-term retention.

What license is Faramesh under?

Faramesh Core is available under the Elastic License 2.0. See the License section for details.

About

faramesh-core

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

There was an error while loading. Please reload this page.

Stars

Watchers

Forks

Releases

Packages

  0

Uh oh!

There was an error while loading. Please reload this page.

Languages

Footer

Footer navigation