Governance Concepts
This page explains the core concepts that appear across the Control Plane. Use it as a reference when configuring agents, policies, or reviewing execution records.
Agent identity types
Every agent declares how it proves its identity to KeyRunner. This identity determines how confidently KeyRunner can verify the agent is who it claims to be.
| Identity type | What it means |
|---|---|
| Kubernetes | The agent runs as a Kubernetes service account and proves its identity via a cryptographic OIDC token from your cluster. Strongest cloud-native option. |
| AWS | The agent assumes an AWS IAM role. Identity is verified using AWS's own credential chain. |
| GCP | The agent runs as a GCP service account, optionally using Workload Identity Federation. |
| Azure | The agent uses an Azure managed identity, verified against Azure Active Directory. |
| Claude | An Anthropic Claude model is acting as the agent. Identity is declared by model ID and organization. |
| OpenAI | An OpenAI model is acting as the agent. Identity is declared by model ID and organization. |
| Cursor | A Cursor IDE instance is acting as the agent. |
| API key | The agent authenticates with a static API key. KeyRunner stores only the key prefix, not the full key. |
| None | No identity is configured. Not recommended for production - the agent cannot be verified. |
Cloud infrastructure identities (Kubernetes, AWS, GCP, Azure) are cryptographically verifiable and considered the strongest. API keys and AI model identities are moderate. No identity is unverified.
Lifecycle shapes
When you configure an agent's governance contract, you choose a lifecycle shape. This describes how observable and reversible the agent's tool calls are - which in turn determines what governance actions KeyRunner can take if something goes wrong.
| Shape | Observable | Reversible | What it means in practice |
|---|---|---|---|
| async_governed | Yes | Yes | KeyRunner can monitor progress and cancel or roll back if needed. The most governable option. |
| blind_async | Yes | No | KeyRunner can see when the call completes, but cannot cancel it once dispatched. |
| irreversible_tracked | No | Yes | KeyRunner can cancel the call but cannot monitor its progress once it starts. |
| fire_and_forget | No | No | The call is dispatched and recorded, but KeyRunner has no further visibility or control. |
Choose async_governed for any action with significant consequences - payments, infrastructure changes, data writes. Use fire_and_forget only for truly one-way actions where all you need is an audit record, such as sending a metric or writing a log.
How a tool call is evaluated
Every tool call an agent attempts goes through the same sequence of checks:
- Is the tool name registered in this workspace?
- Is the tool approved (not pending or rejected)?
- Is the tool currently enabled?
- Does at least one of the agent's policies cover this tool?
- Does the matching policy require human approval?
If any check from 1 to 4 fails, the call is blocked and the agent receives a reason.
If check 5 is true, the call is held for approval (or flagged for retrospective review).
If all checks pass and no approval is required, the call is allowed and runs immediately.
When a call is blocked
When a call is blocked, the agent receives a structured response that includes:
- The reason it was blocked (not registered, not approved, disabled, or not in any policy)
- Whether the block can be escalated to a human approval request
- If it can be escalated, the endpoint to create that request
This means agents can be built to self-escalate when they hit a permission boundary, rather than simply failing.
Time-bound approvals
When a human approves a tool call, they can set limits on how long that approval is valid:
Expiry date - the approval automatically ends at a specific date and time. The next call after the expiry creates a new pending request. Use this when you are granting access only during a specific window, such as a maintenance period.
Use limit - the approval ends after a specific number of uses. A limit of 1 means a single one-time authorization. Use this when you want to allow an action a fixed number of times before requiring another review.
Both limits can be combined. The approval closes when the first one is reached.
When an approval closes, the agent is not permanently blocked - the next attempt creates a fresh request for the approver to review again.
Protecting sensitive data in logs
Tool calls sometimes involve or return sensitive information - API keys, payment card numbers, passwords. KeyRunner's redaction rules let you specify which data fields should never appear in execution logs.
When a tool has redaction rules, KeyRunner replaces the listed field values with [REDACTED] before writing the log entry and before returning the result to the agent. The original values are never stored.
This protection is applied on KeyRunner's servers - the agent process itself never receives the raw sensitive values in the log record. Even if agent logs or memory are compromised, the redacted fields are not present.
Redaction rules are configured per tool in the Tools page.