Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.brane.membranelabs.org/llms.txt

Use this file to discover all available pages before exploring further.

Install brane-core and govern your first tool capability.

​
Install

pip install brane-core
Package name may change before the stable release. Check the GitHub repo for the latest install instructions.

​
Create a Runtime

A Runtime is the coordinator for capabilities and policies. Create one per agent process. 
from brane import Decision, Runtime

runtime = Runtime(agent_id="data-agent", environment="dev")

​
Register a Capability

Use the @runtime.capability decorator to turn a function into a governed capability. The decorator registers the capability in the runtime’s capability registry and wraps the function so every call passes through the policy engine. 
@runtime.capability(name="execute_sql", type="tool", risk="high")
def execute_sql(query: str):
    return {"rows": []}

​
Write a Before Policy

A before_capability policy runs before the function executes. Return Decision(type="deny") to block the action. Return Decision(type="allow") to let it proceed. 
@runtime.before_capability("execute_sql")
def read_only_sql(ctx):
    if not ctx.arg("query").lower().strip().startswith("select"):
        return Decision(type="deny", reason="Only SELECT queries are allowed")
    return Decision(type="allow")

​
Call the Capability

# Allowed: query starts with SELECT
result = execute_sql("select * from customers limit 10")
# Returns: {"rows": []}

# Denied: query starts with DELETE
execute_sql("delete from customers")
# Raises: CapabilityDeniedError: Only SELECT queries are allowed

​
Handle the Error

from brane import CapabilityDeniedError

try:
    execute_sql("delete from customers")
except CapabilityDeniedError as e:
    print(f"Blocked: {e.reason}")
    print(f"Policy: {e.policy_name}")
    print(f"Action ID: {e.action_id}")

​
What Happened

When you called execute_sql("delete from customers"), Brane:
  1. Intercepted the function call
  2. Created an AgentAction record for the attempt
  3. Built a PolicyContext with the capability, arguments, and runtime metadata
  4. Found the read_only_sql policy matching the execute_sql capability
  5. Evaluated the policy; it returned Decision(type="deny")
  6. Raised CapabilityDeniedError without calling the underlying function

​
Complete Example

from brane import CapabilityDeniedError, Decision, Runtime

runtime = Runtime(agent_id="data-agent", environment="dev")

@runtime.capability(name="execute_sql", type="tool", risk="high")
def execute_sql(query: str):
    return {"rows": []}

@runtime.before_capability("execute_sql")
def read_only_sql(ctx):
    if not ctx.arg("query").lower().strip().startswith("select"):
        return Decision(type="deny", reason="Only SELECT queries are allowed")
    return Decision(type="allow")

# Allowed
result = execute_sql("select 1")
print(result)  # {"rows": []}

# Denied
try:
    execute_sql("delete from customers")
except CapabilityDeniedError as e:
    print(f"Blocked: {e.reason}")

​
Next Steps