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

# Runtime

> The Runtime is the coordinator for capabilities and policies in brane-core.

The coordinator for capabilities and policies. Create one per agent process.

## Definition

A Runtime owns the capability registry, the policy engine, and the interception machinery. You create one per agent process, configure it with capabilities and policies, and let it govern all capability calls.

## Constructor

```python theme={null}
from brane import Runtime

runtime = Runtime(
    agent_id="support-agent",
    environment="prod",
    tenant_id="tenant_acme",
    principal_id="user_sarah",
)
```

All constructor arguments are optional.

| Argument       | Type               | Description                                |                                                               |
| -------------- | ------------------ | ------------------------------------------ | ------------------------------------------------------------- |
| `agent_id`     | \`str              | None\`                                     | Identity of this agent. Used in every AgentAction record.     |
| `environment`  | \`str              | None\`                                     | Runtime environment: `dev`, `staging`, `prod`.                |
| `tenant_id`    | \`str              | None\`                                     | Default tenant for all actions. Can be overridden per action. |
| `principal_id` | \`str              | None\`                                     | Default principal for all actions.                            |
| `capabilities` | `list[Capability]` | Pre-register capabilities at construction. |                                                               |
| `policies`     | `list[Policy]`     | Pre-register policies at construction.     |                                                               |

## Owned Components

| Attribute      | Type                            | Purpose                                                        |
| -------------- | ------------------------------- | -------------------------------------------------------------- |
| `capabilities` | `CapabilityRegistry`            | Stores and retrieves registered capabilities.                  |
| `policy`       | `PolicyRegistry`                | Stores registered policy functions.                            |
| `policies`     | `PolicyEngine`                  | Evaluates actions against registered policies.                 |
| `interceptor`  | `CapabilityInterceptor`         | Core intercept-evaluate-execute loop.                          |
| `callables`    | `CallableCapabilityInterceptor` | Wraps Python callables with interception and argument binding. |

## Methods

```python theme={null}
runtime.register_capability(capability: Capability)
```

Register a capability in the capability registry.

```python theme={null}
runtime.capability(name, type, risk, **kwargs)
```

Decorator that registers the function as a governed capability and wraps it with policy enforcement.

```python theme={null}
runtime.wrap_capability(fn, name, type, risk, **kwargs)
```

Wrap an existing function as a governed capability without decorator syntax.

```python theme={null}
runtime.before_capability(target, name=None, version=None)
runtime.after_capability(target, name=None, version=None)
```

Register policies that run before or after a capability executes.

```python theme={null}
runtime.create_action(capability_name, input, action_type=None)
runtime.evaluate_action(action)
runtime.evaluate(capability_name, input)
```

Create and evaluate actions manually.

## Common Setups

Minimal local development:

```python theme={null}
runtime = Runtime(agent_id="my-agent")
```

Full production context:

```python theme={null}
runtime = Runtime(
    agent_id="support-agent",
    environment="prod",
    tenant_id=request.tenant_id,
    principal_id=request.user_id,
)
```

Pre-registering capabilities and policies:

```python theme={null}
from brane import Capability, Policy, Decision, Runtime

cap = Capability(name="send_email", type="tool", risk="medium")

def block_external_domains(ctx):
    to = ctx.arg("to", "")
    if not to.endswith("@acme.com"):
        return Decision(type="deny", reason="External email addresses are blocked")
    return Decision(type="allow")

policy = Policy(
    target="send_email",
    stage="before_capability",
    function=block_external_domains,
    name="block_external_email",
)

runtime = Runtime(
    agent_id="comms-agent",
    capabilities=[cap],
    policies=[policy],
)
```

Per-request runtime for multi-tenant systems:

```python theme={null}
def handle_request(request):
    runtime = Runtime(
        agent_id="support-agent",
        environment="prod",
        tenant_id=request.tenant_id,
        principal_id=request.user_id,
    )

    runtime.register_capability(SHARED_REFUND_CAP)
    runtime.before_capability("refund_customer")(refund_policy)
```

<Note>
  One runtime per agent process is the recommended pattern. If you need different tenant or principal contexts per request, create a new Runtime per request with the appropriate identity fields, or override them per `create_action` call.
</Note>

## Future Constructor Arguments

* `audit`: AuditSink for recording action events
* `approvals`: ApprovalProvider for handling `approval_required` decisions
* `cloud`: CloudClient for remote policy evaluation
* `grants`: GrantRegistry for agent capability grants
* `fail_mode`: fail-open or fail-closed on policy engine errors