llms.txt
Compare with other sites' llms.txt files →# OpenAPPA
> OpenAPPA is an open-source, deterministic security engine for real-world agentic applications.
## Docs
- [What is OpenAPPA](/): OpenAPPA is an open-source, deterministic security engine for real-world agentic applications.
- [How it works](/how-it-works): Deterministic security guarantees, flow tracking, and how agents self-correct.
- [Policy configuration](/contracts): TOML configuration for tool contracts, restrictions, annotations, and remedy plans.
- [Coding agents](/coding-agents): Tool-flow enforcement, file labels, SafeBash, shell rules, and checked delegation for coding agents.
- [Archestra](/archestra): Run OpenAPPA at the LLM proxy level with the Archestra platform.
- [Claude Code](/claude-code): Protect Claude Code sessions with deterministic information-flow control in your terminal.
- [What is a battery](/batteries): How batteries are structured, combined, and run.
- [Available batteries](/available-batteries): OpenAPPA batteries for popular MCP servers and tools.
- [Slack battery](/battery-slack): Rules for all 19 claude.ai Slack connector tools, with audiences from Slack channels, users, and groups.
- [Claude Code tools battery](/battery-claude-code): File labels for Claude Code's Read, Write and Edit, shell commands confined to what they declare, and rules for the tools only Claude Code offers.
- [GitHub battery](/battery-github): Rules for the GitHub MCP server's 44 default tools; each repository's visibility decides its readers.
- [Grain battery](/battery-grain): Rules for 49 Grain meeting, transcript, deal, and administration tools.
- [Google Workspace battery](/battery-google-workspace): Rules for the claude.ai Google Drive connector's 11 tools, with audiences from your Google Workspace directory and groups.
- [Linear battery](/battery-linear): Rules for 65 Linear MCP tools with per-issue, per-team, and per-project audiences, and reviewed writes.
- [Sentry battery](/battery-sentry): Rules for the Sentry MCP server's 9 listed tools and 55 catalog tools, with internal reads and reviewed writes.
- [Notion battery](/battery-notion): Rules for the hosted Notion MCP server's 36 tools, with internal reads and reviewed structural changes.
- [Microsoft Learn battery](/battery-microsoft-learn): Rules for the Microsoft Learn MCP Server's 3 read-only documentation tools, with public queries and untrusted results.
- [Cloudflare battery](/battery-cloudflare): Rules for Cloudflare's documentation and Workers Observability MCP servers: public documentation reads, internal logs, telemetry and Worker reads, no writes.
- [Create your own battery](/write-a-battery): Create, test, and submit a battery for your MCP server.
- [LaunchDarkly battery](/battery-launchdarkly): Rules for LaunchDarkly's official MCP server, all 20 tools, with internal reads and every write reviewed.
- [PostHog battery](/battery-posthog): Rules for PostHog's MCP server, all 44 registry tools, with internal analytics reads and reviewed writes.
- [PagerDuty battery](/battery-pagerduty): Rules for the PagerDuty-hosted MCP server's 18 tools, with internal reads and every write reviewed.
- [Databricks battery](/battery-databricks): Rules for Databricks' Genie One and Databricks SQL managed MCP servers, with internal reads, every SQL statement classified before it runs, and the databricks audience source.
- [Hugging Face battery](/battery-huggingface): Rules for the hosted Hugging Face MCP server's 11 tools; each repository's visibility on the Hub decides its readers.
- [Archestra battery](/battery-archestra): Rules for every tool of Archestra's built-in MCP server, with shares checked against the teams and members they reach.
- [monday battery](/battery-monday): Rules for monday Platform MCP's 99 tools, with internal reads and reviewed writes and sensitive changes.
- [xmemory battery](/battery-xmemory): Rules for the hosted xmemory instance and admin MCP servers' 32 tools, with internal reads and reviewed schema migrations and instance deletion.
- [kAgent](/kagent): Protect kagent declarative Python and Go Agents with OpenAPPA policy.
- [Pi](/pi): Protect Pi coding agent sessions with OpenAPPA through the community pi-openappa extension.
- [AppenCode](/opencode): Protect OpenCode sessions with deterministic information-flow control.
- [Add to your agent](/add-to-agent): Embed APPA in your own agent, connect a coding agent through hooks, or use it through the Archestra LLM proxy.
- [Validation](/validation): Test policy decisions before merging changes, without running your agent's tools.
- [Observability](/observability): Export bounded runtime telemetry to your existing observability tools and use it to investigate agent activity.
- [Reporting (appa yell)](/yell): Agents report confusing blocks and suspected policy misconfigurations through the yell tool, giving policy maintainers evidence for improvements.
- [Self-improving policies](/self-improving-policies): Report confusing decisions with appa yell, then propose tested changes to appa.toml.
- [Benchmarks](/evaluation): Evidence for OpenAPPA's security, utility, and token cost across three agent benchmarks.
- [OpenAPPA vs Cedar](/openappa-vs-cedar):
- [OpenAPPA vs Dogwood](/openappa-vs-dogwood):
- [OpenAPPA vs OPA](/openappa-vs-opa):
- [OpenAPPA vs Agent Auto-Modes](/openappa-vs-auto-mode): Comparing OpenAPPA's deterministic information-flow control with Claude Code's auto mode and Codex's auto-review.
- [Advisory Board](/advisory): Engineers from different companies, reviewing OpenAPPA as it takes shape.
- [Branding](/branding): The OpenAPPA mark, wordmark and lockup, as the site itself renders them.
## Optional
- [MCP server](/mcp): the same docs as an auth-less MCP server (streamable HTTP)
---
# What is OpenAPPA
> OpenAPPA is an open-source, deterministic security engine for real-world agentic applications.
OpenAPPA is a frontier deterministic AI guardrail that is 100% resistant to data exfiltration caused by prompt injection or model hallucination, and the first of its kind that doesn't break agents.
Backed by a [NeurIPS-accepted paper](/paper), it is open, vendor-agnostic, and MIT-licensed.
And yes, it outperforms competitors on benchmarks:
**Task completion**
- OpenAPPA: 89%
- Claude Auto mode: 90%
- FIDES (Microsoft): 41%
**Successful attacks**
- OpenAPPA: 0%
- Claude Auto mode: 10%
- FIDES (Microsoft): 31%
[Read the full benchmark results](/evaluation)
## Non-deterministic guardrails miss the problem
The industry's answer to approval fatigue is a second model that judges each tool call: Claude Code's auto mode, Codex's auto-review, and other [auto-modes](/openappa-vs-auto-mode).
By design, they cannot track data flow across tool calls. Because classifiers are prompt-injectable themselves, harnesses hide tool outputs from them, so the judge never sees the data at all.
Because of their probabilistic design, even the best top out at [99.3%](https://openai.github.io/openai-guardrails-python/ref/checks/prompt_injection_detection/): at millions of calls, 0.7% is a lot of breaches.
## Other deterministic guardrails either break agents or don't work
Blacklisting commands against an LLM is a dead end. Block `rm -rf /` and the model writes a Python one-liner; block `curl` and it pushes to an external git remote. A list of regexes also gives zero visibility into coverage: nobody can verify that it closes every path, or that three mundane tools chained together don't leak.
Rule sets end up either so tight they break the agent or so intricate nobody can audit what they permit.
## OpenAPPA tracks flows instead of matching patterns
OpenAPPA is a cross-platform, pluggable engine driven by a [single configuration](/contracts). It runs outside the agent's prompt and execution loop, so the model cannot see, negotiate with, or manipulate it, and it [plugs into an existing agent loop](/add-to-agent) in one place.
[Figure: a stack of OpenAPPA policy TOML files applied to coding agents, LLM proxies, MCP gateways, MCP servers, and agents in production.]
Instead of allowed and blocked tools, the configuration describes data sources, [audiences](/contracts#audiences), [trust levels](/contracts#trust), and [authorities](/contracts#authorities). Every trajectory carries a security label, `audience × trust`: reading a private repo narrows the audience, reading an unvetted web page lowers trust. The label only ever gets more restrictive, and the engine derives each decision from it algebraically.
An injected prompt telling the agent to leak secrets is irrelevant: you cannot prompt-inject an algebra. Because the configuration is declarative, you can [validate in CI/CD](/validation) that your whole tool graph is covered. The configuration is data-specific, so you can scale to millions of agents without changing it.
## It's full of tricks to help agents accomplish their tasks
Strict enforcement is where utility usually dies: a bare "forbidden" makes an agent stall, retry, and fail. OpenAPPA instead returns a machine-readable [remedy plan](/how-it-works#keeping-agents-useful-under-restrictions) with the ways the agent may legally proceed:
- **Sanitizers** transform the payload, masking secrets or redacting PII, so it can flow to a wider audience. Stock sanitizers ship in the box; custom ones, including model-based ones, plug in with a clear blast radius.
- **Authorities** approve one specific action, through a human or an internal API, without lifting the session's restrictions for later calls.
- **Subagents** isolate an untrusted read in a disposable branch, so the parent trajectory continues unpoisoned.
This is what lifts task completion from 37% to 90% on our [benchmarks](/evaluation) and makes deterministic security practical.
---
# How it works
> Deterministic security guarantees, flow tracking, and how agents self-correct.
## OpenAPPA enforces information-flow policy proactively
OpenAPPA sits between an agent and its tools to answer one question before every action: *is this data allowed to go to this destination?*
Powered by **APPA** (Agentic Permissions Policy Algebra), OpenAPPA tracks data sensitivity and trust across the tools an agent uses. The security engine stays outside the agent loop, so prompt injections cannot alter or bypass policy rules.
OpenAPPA also helps the agent remain useful under security restrictions. If an action is blocked by policy, OpenAPPA returns ways to continue: request human approval, clean sensitive fields, or isolate a read in a subagent.
## The Core Concepts
OpenAPPA operates with three concepts:
1. **Security Label**
A trajectory is an agent's work on a conversation or task, including its tool calls. For each trajectory, OpenAPPA keeps a security label and the policy configuration needed to evaluate its next action. Each decision accounts for what the agent has already read and done.
The security label can become more restrictive as the agent works, but it cannot become less restrictive. Once the agent reads restricted or untrusted data, those restrictions stay with the session.
:::fig-label-fold:::
Audience and Trust make up the security label. OpenAPPA also tracks Effects and checks Attention requirements:
1. **Audience:** Who is authorized to access data in this agent session. Reading data for a smaller audience restricts where the agent can send data later. For example, after reading an internal customer record, the agent cannot send session data to a public destination. An audience can be as specific as the members of one Slack channel: the contract extracts the channel ID from the tool's arguments, so reading channel `C0123` labels the data with that channel's membership, and posting to it requires that they are already valid readers.
2. **Trust:** How much the data in the session can be trusted. Trust follows who can write the text, not who can read it. Text that only members of the organization and its collaborators wrote, such as a team discussion in an internal channel or on a public repository, keeps the session's trust, and so does text one accountable publisher controls, such as a vendor's documentation or a release index. Text on a surface anyone can write to, such as a forum answer or an outside contributor's comment, lowers it, and tools that require trusted input will no longer be allowed to run.
3. **Effect:** What the agent has already done, such as sending an email or changing a system. Effects accumulate in the session history. A policy can require an effect to have happened, or prevent an action after an effect has happened.
4. **Attention:** Approval or review required for a specific action. Unlike effects, attention does not accumulate. An approval clears the attention requirement for that action only, and later calls must request attention again.
2. **Tool Contracts**
Every tool has a contract in the OpenAPPA policy. The contract tells OpenAPPA how the tool interacts with the agent's security state:
- **`delta`:** How data returned by the tool changes the security label.
- **`forwards`:** The label of content the tool sends beyond its arguments, such as a stored file that it mails. Most tools omit it.
- **`requires`:** Which requirements the data the call sends must satisfy for OpenAPPA to allow the action. OpenAPPA checks them before the call: against the session's label, combined with `forwards`.
- **`effects`:** Which effects are recorded after a tool runs successfully.
OpenAPPA uses the first explicit contract whose argument selectors match. If none match, the policy can route the call through a wildcard (`name = "*"`) annotator. Once a contract matches, a schema error refuses the call without falling through.
For example, a CRM tool can label its result as internal, while an email tool can require the recipient to be included in the session's audience.
3. **Remedy Plans**
When an action does not meet its tool contract, OpenAPPA blocks it and returns the remedy plans allowed by the policy. A plan can involve cleaning data with a [sanitizer](#sanitizers), receiving approval from an [authority](#authorities), accepting a narrower audience, withholding a tool result, or isolating a sensitive read in a [subagent](#subagent-reads).
An offered plan can still be denied by an approval service or fail during data cleaning. If no permitted remedy succeeds, the action remains blocked.
:::fig-remedy-plan:::
## Keeping Agents Useful Under Restrictions
If the security label becomes more restrictive as the agent works, how can the agent still do something useful?
OpenAPPA can ask for approval for a specific action or clean data before the agent sees it. It also uses information about each tool call and who may access the data to apply the appropriate restrictions. The policy configuration defines when these options are available.
### Authorities
An authority can approve a specific action that the session's restrictions would otherwise block. It can be a person, an approval service, or an LLM evaluator. Approval does not make the security label less restrictive; it only allows that one action.
For example, an agent has read a private customer report and wants to email it to an external auditor. An authority can approve that email without approving future emails or changing the session's restrictions.
```toml
[[policy.authority]]
name = "reviewer"
[policy.authority.permits]
# Allow the reviewer to approve sharing
# outside the session's audience.
audience_missing = ["public"]
[externals.authorities.reviewer]
# OpenAPPA's built-in human-in-the-loop authority.
builtin = "hitl"
```
See [Authorities in Policy configuration](/contracts#authorities) for configuration and supported implementations.
### Sanitizers
A sanitizer cleans data before the agent receives it or sends it to a tool. Cleaning data before the agent sends it can allow an action that would otherwise be blocked.
For a side-effecting tool result the integration can withhold, the agent can instead run the tool without receiving any result output. A successful call still records its effects, but its result adds no Value or Label restriction to the trajectory.
For example, a sanitizer removes customer names and email addresses from a support ticket. The policy permits the agent to share that cleaned version in a public bug report.
```toml
[[policy.sanitizer]]
name = "remove_customer_details"
on = ["tool_output"]
[policy.sanitizer.permits]
# Allow the cleaned result to be shared publicly.
audience = { from = ["internal"], to = ["public"] }
[externals.sanitizers.remove_customer_details]
# Replace with your internal sanitization service URL.
url = "https://sanitizer.corp.example/sanitize"
```
See [Sanitizers in Policy configuration](/contracts#sanitizers) for service configuration and where cleaning can happen.
### Annotators
An annotator classifies a tool call. It can determine the call's output restrictions (`delta`), the restrictions of content it sends (`forwards`), requirements (`requires`), and effects. The `jev` builtin determines audience and trust only: no effects, history, or attention marks. OpenAPPA checks the resulting contract before allowing the call.
For example, a Python script can classify files by directory: files in `/srv/public-docs` can be shared publicly, while files in `/srv/customer-records` are restricted to internal users.
```toml
[[policy.annotator]]
name = "classify_file"
ranks = ["suspicious"]
audiences = ["internal"]
marks = []
effects = []
[[policy.tool]]
name = "read_file"
# Ask the annotator to classify the file being read.
annotator = "classify_file"
[externals.annotators.classify_file]
command = ["python3", "./classify_file.py"]
```
An annotator can run as a local script or an external service. When the call itself does not say what the annotator needs to know — a `git push` names a remote, not who can read the repository, and `gh pr view` names a number, not who wrote the comments — a context provider of the deployment finds the facts first, and the annotator classifies from them. See [Annotators in Policy configuration](/contracts#annotators) for configuration, the request and response format, and limits on its answers.
### Subagent Reads
A subagent reads sensitive data in a separate context and returns only what the policy allows. For example, it can summarize a private ticket and pass the summary through a sanitizer, letting the main agent use the cleaned result in a public bug report if the policy permits.
Before the subagent starts, the main agent sets the return requirements, including any cleaning. These also limit what the subagent can read. OpenAPPA blocks results that do not meet them.
See [Subagent Returns](/contracts#subagent-returns) for integration requirements and configuration.
### Subagent forks and root forks
A `trajectory family` contains one root and its spawned subagents in the same event log. OpenAPPA distinguishes a `subagent fork` inside that family from a `root fork` that starts another family.
| Operation | What opens | What remains connected |
|---|---|---|
| Resume or compact a conversation while keeping its session ID | The existing root reopens. | Its existing policy state and history remain in place. No fork is needed. |
| Spawn a subagent, such as Claude Code's `Agent` tool | A child trajectory binds to an approved spawn in the same family. | The family shares effect history, and a child answer crosses a checked return path. |
| Run a `fan-out spawn`, such as Claude Code's `Workflow` tool | Each subagent the spawn starts binds its own fork under the spawn's one approval, starting at the parent's label at that moment. | The same as a single spawn, for each subagent: every answer crosses the checked return path on its own. |
| Open an independent conversation from copied context | The embedding integration can open a new root family from an identified source trajectory. | Only the source