Faramesh Docs

Quickstart

Install the CLI, generate governance.fms, wire your agent, and run a governed stack end to end. Copy each block as written.

This page is a single path from zero to a governed agent. Run each block in order. Every command is copy-paste ready.

You need: a terminal, Python 3.10+ for the LangGraph example (TypeScript works the same), and an empty project directory.

Install the CLI

Pick one method. After any method, run faramesh version and confirm you see a version string.

Terminal
curl -fsSL https://raw.githubusercontent.com/faramesh/faramesh-core/main/install.sh | bash
faramesh version

Non-interactive (CI):

Terminal
curl -fsSL https://raw.githubusercontent.com/faramesh/faramesh-core/main/install.sh | bash -s -- --no-interactive
faramesh version

Installs the release binary for your OS and architecture, verifies SHA256, and places faramesh on your PATH.

Terminal
brew tap faramesh/tap
brew install faramesh
faramesh version

Requires Homebrew on macOS or Linux. The formula builds from source via Go.

Run without a global install:

Terminal
npx @faramesh/cli@latest version

Or install globally:

Terminal
npm install -g @faramesh/cli
faramesh version

Requires Node.js 18+.

Terminal
go install github.com/faramesh/faramesh-core/cmd/faramesh@latest
faramesh version

Ensure $(go env GOPATH)/bin is on your PATH.

Terminal
git clone https://github.com/faramesh/faramesh-core.git
cd faramesh-core
go build -o faramesh ./cmd/faramesh
export PATH="$(pwd):$PATH"
faramesh version

Optional system-wide install:

Terminal
sudo install -m 0755 faramesh /usr/local/bin/faramesh
faramesh version

Requires Go 1.22+.

Create a project directory

Terminal
mkdir my-governed-agent && cd my-governed-agent

Use your existing agent repo instead if you already have one. Run the rest from that directory root.

Generate governance.fms

Terminal
faramesh init

Expected output includes Framework detected, Tools discovered, and governance.fms written.

Validate:

Terminal
faramesh check

Start the daemon (dev mode)

Terminal 1:

Terminal
faramesh dev

Leave this running. Note the socket path (default ~/.faramesh/runtime/faramesh.sock).

Wire your agent

Open your agent entry file in an editor (nano, vim, VS Code, or Cursor). Paths below assume project root.

Tier: in-process SDK shim. Frameworks: LangGraph, LangChain, CrewAI, OpenAI Agents, Google ADK, and others.

File: agent.py (or your main agent module) in the project root.

Install the SDK:

Terminal
pip install faramesh-sdk

Edit agent.py. Replace the tools list passed to your graph:

agent.py
import os
from faramesh import GovernedToolSet
from langgraph.prebuilt import create_react_agent

os.environ.setdefault("FARAMESH_AGENT_ID", "myproject-agent")

tools = GovernedToolSet(
    [search_docs, send_email, charge_card],
    agent_id="myproject-agent",
)

graph = create_react_agent(model, tools)
agent.ts
import { governedTools } from '@faramesh/sdk';

export const tools = governedTools(
  { searchDocs, sendEmail, chargeCard },
  { agentId: 'myproject-agent' },
);

Install: npm install @faramesh/sdk

Run (terminal 2):

Terminal
export FARAMESH_SOCKET=~/.faramesh/runtime/faramesh.sock
python agent.py

More frameworks: LangGraph, LangChain, OpenAI Agents, CrewAI.

Tier: MCP proxy. Clients: Claude Code, Cursor, OpenCode.

File: governance.fms in the project root. Add:

governance.fms
runtime {
  mode           = "enforce"
  mcp_proxy_port = 8081
}

Apply:

Terminal
faramesh apply

File: Claude Code MCP config (path varies by install). Example ~/.claude/claude_desktop_config.json or project .mcp.json:

MCP config
{
  "mcpServers": {
    "my-tools": {
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}

Point each upstream MCP server through the Faramesh proxy URL. Full steps: Claude Code, Cursor.

Tier: HTTP proxy. Runtimes: Bedrock action groups, OpenAPI tool endpoints.

File: governance.fms in the project root:

governance.fms
runtime {
  mode        = "enforce"
  http_listen = "0.0.0.0:8443"
}
Terminal
faramesh apply

Point Bedrock or your API gateway at https://<host>:8443/... instead of the raw handler. Details: Bedrock.

Tune policy (optional)

File: governance.fms in the project root.

governance.fms
agent "myproject-agent" {
  rules {
    permit search_docs
    defer  send_email
    permit charge_card if amount < $50
    deny   charge_card if amount >= $50
  }
}
Terminal
faramesh check
faramesh plan

Restart faramesh dev in terminal 1 after edits (Ctrl+C, then faramesh dev again).

Watch decisions

Terminal 3:

Terminal
faramesh approvals list
faramesh audit tail

Approve a deferred call:

Terminal
faramesh approvals approve apr-9001

Production path (when ready)

Terminal
faramesh dev
export FARAMESH_SOCKET=~/.faramesh/runtime/faramesh.sock
python agent.py

In-process stubs. No Vault or KMS required.

Terminal
faramesh apply
.faramesh/bin/agent -- python agent.py

Persistent WAL and optional OS sandbox. See From dev to production.

Verify the stack

Terminal
faramesh status
faramesh audit verify

Next

Why Faramesh

What agent governance is for, who it helps, and when to reach for Faramesh before something goes wrong in production.

Use cases

Concrete scenarios where teams put Faramesh in production, payments agents, support bots, internal automation, coding agents, multi-tenant SaaS, regulated industries.

On this page

Install the CLICreate a project directoryGenerate governance.fmsStart the daemon (dev mode)Wire your agentTune policy (optional)Watch decisionsProduction path (when ready)Verify the stackNext