# Shadow mode and replay

Evaluate policy impact before enforcement and understand historical coverage.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/policies/shadow-replay

## Shadow mode

An environment in shadow mode records how policy would affect supported actions while allowing work to proceed. Confirm that the environment is intentionally in shadow mode; billing-driven observe-only is a separate state with a different cause.

Review would-block activity, false positives, and the active policy revision before switching to enforcement. A shadow outcome does not prove that an action was blocked.

## Replay a candidate

The operator CLI can simulate a `.kastra` policy against retained traffic:

```text
kastra policy simulate ./policy.kastra --against-traffic --from YYYY-MM-DD
```

Choose a real start date and the intended environment. This is a read/analysis workflow; it does not rerun the original tools. Compare changed decisions and representative examples before activation.

## Coverage limits

Replay depends on retained inputs, masking, available attributes, and the recorded time range. Missing or truncated context can make historical evaluation incomplete. Do not describe a replay as covering actions absent from the log or formats the original integration did not capture.

## Promote a reviewed policy

Export or promote the policy, verify its target environment and revision, then activate deliberately. Keep rollback information available. After activation, inspect actual decisions because a good historical fit does not guarantee future behavior.