Hardalion Docs
NexusDevelopersQuickstart

Shadow mode

Test policies on live traffic without blocking production

Shadow mode

Shadow mode lets you deploy Nexus on production agent traffic without blocking execution. The policy engine evaluates every tool call and records what would have happened if enforcement were active.

Use shadow mode to validate policy packs, tune thresholds, and build compliance evidence before flipping to enforce mode.

How it works

flowchart LR
  A[Tool call] --> B[NPL evaluation]
  B --> C{Decision}
  C -->|ALLOW| D[Execute + audit]
  C -->|BLOCK| E[Execute anyway]
  E --> F[Log counterfactual BLOCK]
  F --> G[Shadow metrics]

In shadow mode:

  • ALLOW decisions behave normally
  • BLOCK and REQUIRE_HUMAN decisions are not enforced
  • Counterfactual decisions append to shadow metrics and the audit log with event type policy.shadow.would_have_blocked

Enable shadow mode

API

curl -X PATCH "https://api.hardalion.com/api/v1/execution-mode" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"execution_mode":"shadow","fail_closed":true}'

Dashboard

Open Shadow metrics in the Nexus console and select Shadow (audit-only).

Pilot workspaces can also set pilot mode to pilot_shadow, which auto-enables tenant execution mode shadow.

Read shadow metrics

curl "https://api.hardalion.com/api/v1/shadow/metrics?period_days=7" \
  -H "Authorization: Bearer $API_KEY"

Response includes wouldHaveBlockedCount, matched rule IDs, and reason codes. Use this data to refine policies before enforcement.

Switch to enforce mode

When shadow metrics show acceptable false-positive rates:

curl -X PATCH "https://api.hardalion.com/api/v1/execution-mode" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"execution_mode":"enforce","fail_closed":true}'

Blocked calls return typed errors with audit metadata. See Agents API.

Fail-closed still applies

Shadow mode bypasses blocking decisions only. Infrastructure failures (policy engine unreachable, missing AgentIAM credential when required) still fail closed in production configuration.

Typical rollout

  1. Deploy SDK wrap on staging with enforce mode
  2. Enable shadow mode on production traffic for 7 to 14 days
  3. Review shadow metrics with compliance stakeholders
  4. Pin policy version and switch to enforce mode
  5. Export conformity evidence via Compliance exports