# Architecture and enforcement coverage

Trace each action through its enforcement point, policy service, and evidence path.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/security/architecture

## Follow the permission boundary

Kastra combines a policy and approval service with integrations that enforce its decisions. The integration supplies action context, receives a result, and controls whether the supported action proceeds. The service manages policy, checkpoints, and recorded decision evidence.

```mermaid
flowchart LR
  subgraph agents["Coding agents"]
    direction LR
    agent["Coding agent"] --> hook["Edge pre-action hook"]
    hook --> evaluation["Kastra evaluation"]
    hook -->|"result"| hosttool["Host tool"]
    evaluation --> record["Decision record"]
  end
```

```mermaid
flowchart LR
  subgraph applications["Applications"]
    direction LR
    app["Application"] --> proxy["Kastra Proxy"]
    proxy --> provider["Model provider"]
    proxy -->|"governed output"| dispatcher["Application tool dispatcher"]
  end
```

```mermaid
flowchart LR
  subgraph mcp["MCP tools"]
    direction LR
    client["MCP client"] --> gateway["Local Kastra gateway"]
    gateway --> server["Local MCP server"]
    gateway <--> evaluation["Kastra evaluation"]
  end
```

The arrows show logical request paths. Use the data-protection guide to review what each request carries; this diagram is not a network isolation claim.

## Match the control to the action

| Integration | Enforcement point | Boundary to validate |
| --- | --- | --- |
| Edge | Supported pre-action hooks exposed by the coding agent | Host invokes the hook and honors its outcome; direct shell activity and missing hooks are outside coverage |
| Proxy | Supported provider requests and model-output processing | Application routes the request through Kastra and honors blocked or held tools before dispatch |
| Local MCP gateway | Wrapped stdio server discovery and tool calls | The host launches the wrapper; direct server connections remain separate |
| Evaluation API | Your application's call before a protected action | Your application submits meaningful context, handles errors, and enforces the returned permission |

Post-action hooks provide audit context after execution. They cannot stop an action that has already completed. The [account MCP connector](https://docs.kastra.ai/mcp/account) reads governance information and has a separate purpose from the local enforcement gateway.

## What remains in your environment

Your organization controls endpoint configuration, application dispatch, provider and tool credentials, network access, and the underlying system permissions. Use least-privilege credentials and the isolation appropriate to the workload alongside Kastra's action decisions.

For example, a rule can require review before an agent edits a deployment file through a supported hook. Repository protection and CI permissions still govern who can merge or deploy that change. This gives the action review a clear place in the wider control design.

## Connectivity and availability

Edge and the local MCP gateway call the configured Kastra service; they are not offline policy engines. Some client failures can allow work to continue. Review [failure behavior](https://docs.kastra.ai/reference/failure-behavior) before selecting the actions that will rely on those integrations.

Cloud, local integrations, and a self-hosted appliance are different deployment choices. Confirm the [available deployment scope](https://docs.kastra.ai/reference/self-hosted) and [platform support](https://docs.kastra.ai/start/platform-support) for your pilot.

## Evidence to collect

Record the request path, integration and client versions, environment, credential type, observed tool attributes, policy revision, execution result, and any fail-open signal. Use a known harmless action to verify the entire path. [Pilot acceptance plan](https://docs.kastra.ai/security/evaluation).