You are viewing the docs for Archestra v1.4. View the latest docs
Managing the Policy
You manage the policy by chatting with the APPA Keeper: change rules in plain words, add batteries for your MCP servers, check the policy with validations, and fix what keeps agents stuck.
Changing the Policy
You change the policy by chatting with the APPA Keeper, the built-in agent that writes the rules for you. On Overview, click Chat with APPA Keeper, or pick one of the suggested questions next to it.
Ask it in plain words, for example:
- "Require a review before anything is posted to Slack."
- "After the agent reads a web page, block sending email outside the company."
To see your policy, open the Policy tab, or ask the APPA Keeper to explain it.

A change that cannot be applied never turns Guardrails off. The last working policy stays enforced, and the Policy tab shows why the change was refused.
Batteries
A battery is a ready-made set of rules for one MCP server, such as GitHub, Linear, or Google Workspace. Include one, and that server's tools are covered without writing rules.
Ask the APPA Keeper, for example "Cover my GitHub server with a battery". It proposes the batteries that fit your MCP servers, and you approve the change.
Some batteries call an API to decide, for example to check if a repository is public. Such a battery needs a token: the APPA Keeper asks you to set one up in the chat. You can also add it on the Batteries tab: open the battery and set its token under Credentials.

Validating the Policy
A validation keeps one policy scenario checked over time, such as "refuse an email after the agent reads an untrusted page". The APPA Keeper runs your validations before every policy change, so a change that quietly weakens the policy shows up as a failed validation.
Validations are files on the Policy page, listed under Validations beside the policy they check. Open one to read its scenario with the result of its last run marked on each step.

Write a Validation
Click New validation in the Validations header. It opens a chat with the APPA Keeper: tell it the case, for example "check that the agent cannot email outside the company after it reads a web page". Review the scenario it proposes, and approve it.
For more details about validations, check the OpenAPPA validation guide.
Run Validations
Click Run all to check every saved file, or Run file on an open validation to check that one. Every accepted policy change also runs them all.
A step that decided otherwise explains itself under its line, and the Problems panel under the editor lists every failure across files. The dots in a validation's header are its last runs: click one to see that run's result.
What to know:
- A run executes no tools, but asks the policy's annotators and models live, with your organization's credentials. So a run can spend model tokens.
- A run asks no person. A step that expects human review passes when the call offers it.
Required permissions:
guardrailsPolicy:updateto run validations.
Yells
When the agent can't achieve its task because of the policy, it reports the problem via a special yell tool call. The reports are listed in Logs → Guardrails, in one timeline with the Guardrails consults. Set the type filter to Yells to see only the reports.

Open a report and click Investigate in chat. The agent compares the report with the policy and the validations, and proposes a fix.
What to know:
- The Break the glass settings in Settings → Guardrails can let a blocked call through and record the yell for you. Human approval set to waive in unattended sessions (Agent Runtimes, Scheduled tasks, or any client sending
X-Archestra-Unattended: 1; a remedy plan a workload runs counts too) lets a call that waits for a person run, and approves a remedy plan that needs a person for the agent. It can also be kept, the default in this release, or waived everywhere. Other blocked calls, set to Waive the block, releases soft refusals across calls, results, subagent returns, runtime exports, peer messages, and session admission. The first waiver turns Guardrails off for the session. Disabled or failed yell reporting does not prevent the waiver. A call the policy blocks explicitly (theblockedmark) stays blocked regardless of this setting. In this release the deployment sets both withARCHESTRA_andOPENAPPA_ HUMAN_ APPROVAL_ MODE ARCHESTRA_; the settings page shows them read-only. OpenAPPA does not see a waived call: its result is not checked, and its labels and effects are skipped.OPENAPPA_ SOFT_ BLOCK_ MODE - Yell tool, set to Record only, keeps enforcement on after agent reports and human-approval waivers. Other blocked calls, set to Waive the block, always turns enforcement off for the session, regardless of the yell setting.
- Reports stay in your deployment unless you enable external diagnostic forwarding to the shared OpenAPPA reporting service. To turn reports off, set
ARCHESTRA_OPENAPPA_YELL_ENABLED=false.
Required permissions:



