Online vs Offline Mode

SDK supports two basic modes:

Online (Default) — the SDK can load the guardrails policy from Mend and optionally send audit events back to Mend.

Offline — the SDK does not call Mend for policy loading, client registration, audit or other capabilities provided by Mend Platform integration. However, Guardrails checks still run locally on the application machine.

Use offline for local testing, air‑gapped environments, or whenever you do not want the SDK to reach Mend services.

Switching to Offline mode

Can be done in two ways:

Pass offline=True when you create the client (for example MendGuardrailsClient(offline=True)).
Set the environment variable MEND_GUARDRAILS_OFFLINE to true or 1 and leave the client's offline argument unset (defaults follow the env).

If you pass offline=False, that forces online mode even if the env var is set.

Policy Loading

Choosing a guardrail mode can affect the way policy is loaded. It's important to distingish between two scenarios:

You pass a policy when initializing guardrails client (as a file path, JSON file, or dict)
→ That policy is always used. Online/offline does not change it.
You do not pass a policy

Mode	Result
Offline	The built‑in default policy is loaded. Nothing is fetched from the network.
Online	The SDK tries to load the policy from Mend. If any error happens during this process, the offline default policy will be used.

Note: In If Mend says guardrails are turned off for your project, you may get an empty policy (no checks run) until someone turns them back on in Mend. That is different from a connection error, where the SDK usually falls back to the default policy.

License key

You still need a Mend license key regardless of the mode. Offline does not remove that requirement; it only skips Mend policy and audit features as described above.

Periodic configuration refresh (online mode)

In online mode the SDK fetches its configuration from the Mend platform once at initialisation time. To pick up policy changes made on the platform without restarting your application, the SDK performs a lazy on-demand refresh: each guardrail call checks whether the configured interval has elapsed and, if so, re-fetches the policy before running the guardrails for that call.

No background threads are created. The refresh only happens when the SDK is actively being used — if the client is idle there is nothing to update.

Default behaviour: the SDK refreshes at most once every 10 minutes.

Scenario	Result
Refresh succeeds	The active policy is updated before the guardrail call proceeds.
Refresh fails (network error, timeout, …)	A warning is logged, the last successfully fetched policy is retained, and the next attempt is deferred by one full interval.
Two calls arrive simultaneously at the threshold	Only one performs the HTTP fetch; the other proceeds immediately with the current policy.
Offline mode	No refresh is ever attempted; this section does not apply.

Configuring the refresh interval

Set GUARDRAILS_POLL_INTERVAL_MINUTES to a whole-number value before creating the client:

# Refresh every 5 minutes
export GUARDRAILS_POLL_INTERVAL_MINUTES=5

# Disable refreshing entirely — configuration is only loaded at init time
export GUARDRAILS_POLL_INTERVAL_MINUTES=0

The first refresh happens after the first full interval elapses from client creation. Configuration changes will therefore be visible within one interval of being applied on the platform, provided the client receives at least one guardrail call during that window.

Environment variables (quick reference)

Variable	What it's for
`MEND_GUARDRAILS_OFFLINE`	Turn offline on via the environment (`true` or `1`).
`MEND_KEY`	Your Mend key if you do not pass `mend_key=` explicitly.
`GUARDRAILS_AUDIT_URL`	Optional override for where Mend services are reached.
`GUARDRAILS_RUNTIME_CONFIG_TIMEOUT`	How long to wait when fetching policy (seconds; default is 10).
`GUARDRAILS_POLL_INTERVAL_MINUTES`	How often to re-fetch the platform policy in online mode (whole minutes; default is 10). Set to `0` to disable.