Configuration modes

ActionRail supports a code-owned local mode and a Console-managed mode. Both use the same decision pipeline and run Source checks inside the SDK process.

Local configuration

Pass a YAML file path or GroundConfig plus locally constructed Source objects:

from actionrail import enforce
from actionrail.sdk.grounding import SQLiteSource

agent = enforce(
    graph.compile(),
    config="actionrail.yaml",
    sources={
        "billing": SQLiteSource("/var/lib/app/billing.sqlite3"),
    },
)

Minimal actionrail.yaml:

tools:
  issue_refund:
    kind: consequential
    args:
      amount:
        policy: amount <= 200
      order_id:
        ground:
          checks:
            - source: billing
              query: >-
                SELECT customer_id, status
                FROM orders
                WHERE order_id = :value
              match:
                - column: customer_id
                  ctx: customer_id
                - column: status
                  value: delivered

Local mode does not register an agent, report Activity, refresh configuration, or provide a remote review queue. A policy failure therefore returns a held result immediately rather than waiting for Console review.

Console-managed configuration

Pass the registered agent identity instead of config:

agent = enforce(
    graph.compile(),
    agent_id=agent_id,
    api_key=agent_key,
    endpoint="http://127.0.0.1:8020",
)

The runtime fetches:

• the current rule set and monitor mode;
• metadata for Sources referenced by those rules;
• no unreferenced Source configurations.

Only configuration crosses the control-plane boundary. The SDK resolves environment references and connects to each Source locally.

By default, validated configuration refreshes every 30 seconds and swaps atomically between tool calls. A failed refresh retains the last-known-good snapshot.

Hybrid Source injection

Console-managed rules can use Source objects supplied directly by the host application:

agent = enforce(
    graph.compile(),
    agent_id=agent_id,
    api_key=agent_key,
    sources={"billing": application_billing_source},
)

This is useful when connection construction belongs to the application or a custom adapter is not represented in the Console. The Source name must match the name referenced by the rule.

Runtime options

Option	Default	Effect
endpoint	http://127.0.0.1:8020	Control-plane base URL.
monitor	False	Force observe-only rule evaluation.
refresh_interval	30 seconds	Background configuration refresh period; 0 disables refresh.
max_config_staleness	86400 seconds	Maximum age of an unvalidated remote snapshot before enforcement expires.
review_timeout	300 seconds	Maximum time a held call waits for a human decision.
review_poll	2 seconds	Review status polling interval.
state_dir	~/.actionrail/sdk	Configuration cache and durable reporting state.
ctx	{}	Backward-compatible static context defaults. Prefer trusted_context().

Set max_config_staleness=None only when the deployment explicitly accepts unbounded configuration staleness. A negative value is invalid.

Startup behavior

Console-managed startup uses a live configuration response when available. If the Console is unavailable, the SDK can start from a previously validated cache for the same endpoint and agent identity.

Startup fails when there is no valid cached snapshot. It also fails in enforcing mode when the cached snapshot is older than max_config_staleness. Monitor mode may continue to observe with stale configuration because it is not an enforcement boundary.