Getting Started

Quick Start Guide

Get Faramesh up and running in minutes. A production-ready governance system for AI agent actions with policy-based access control, approval workflows, and comprehensive observability.

Installation

Clone the repository and install dependencies

Shell
git clone https://github.com/<org>/fara-core.git
cd fara-core
python3 -m pip install -e ".[test]"

Initialize Database

SQLite is the default for local development

Shell
faracore migrate

Start the Server

Server runs on http://127.0.0.1:8000

Shell
faracore serve

Access the UI

Open http://127.0.0.1:8000 in your browser to access the web interface.

Optional: Set Authentication Token

For production use, set an authentication token:

Shell
export FARA_AUTH_TOKEN=dev-token

Test the Flow

Submit an Action (Python)

Python
from faracore.sdk import ExecutionGovernorClient

client = ExecutionGovernorClient("http://127.0.0.1:8000")

response = client.submit_action(
    tool="shell",
    operation="run",
    params={"cmd": "echo 'Hello FaraCore'"},
    context={"agent_id": "test-agent"}
)

print(f"Action ID: {response['id']}")
print(f"Status: {response['status']}")

Submit an Action (cURL)

Shell
curl -X POST http://127.0.0.1:8000/v1/actions \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "test-agent",
    "tool": "shell",
    "operation": "run",
    "params": {"cmd": "echo test"}
  }'

View Actions in UI

  1. Open http://127.0.0.1:8000
  2. See the action appear in the table
  3. Click the row to see details
  4. If status is pending_approval, click Approve or Deny

Use CLI

Shell
# List actions
faracore list

# Get specific action
faracore get <action-id>

# Approve action
faracore allow <action-id>

# Deny action
faracore deny <action-id>

Policy Configuration

Edit policies/default.yaml to customize rules:

YAML
rules:
  - match:
      tool: "shell"
      op: "*"
    require_approval: true
    description: "Shell commands require approval"
    risk: "medium"

Refresh policy:

Shell
faracore policy-refresh

Learn Concepts

Understand how FaraCore works: actions, policies, and the decision flow.

Read Concepts→

UI Tour

Explore the web interface: action list, filters, approve/deny, and live updates.

Take UI Tour→

Next Steps

  • Customize policies/default.yaml for your use case
  • Integrate the SDK into your agent code
  • Use the UI to monitor and approve actions
  • Check /metrics for Prometheus metrics

Troubleshooting

Server won't start:

  • Check if port 8000 is available
  • Install dependencies: pip install -e .

Actions not showing:

  • Check browser console for errors
  • Verify SSE connection in Network tab
  • Check server logs

Policy not working:

  • Verify policies/default.yaml exists
  • Run faracore policy-refresh
  • Check policy YAML syntax
Next
Concepts