Sources and adapters

A Source is a named configured verification endpoint or instance. An adapter is the reusable implementation that knows how to connect to that type of system.

billing-production  ─┐
billing-sandbox     ─┼─ postgres adapter
refund-ledger       ─┘

The distinction lets one workspace configure multiple Postgres or MySQL databases, HTTP APIs, or MCP gateways without inventing a new adapter for each instance.

Built-in adapters

Adapter	Use it for	Verification request lives in
SQLite	Local examples, embedded applications, tests, small local systems.	Rule check as parameterized SQL.
Postgres	Production relational systems of record.	Rule check as parameterized read-only SQL.
MySQL	MySQL or MariaDB systems of record.	Rule check as parameterized read-only SQL.
HTTP	Internal read APIs and vendor REST endpoints.	Rule check as a path, method, and optional response selector.
MCP	An existing customer MCP gateway exposing a restricted verification tool.	Source as a fixed tool and argument mapping; rule check supplies matching logic.

Configuration split

Create a Source in the Console

For Console-managed agents:

1. Open Sources and choose Add source.
2. Select the adapter and enter its non-secret connection metadata. Store credentials as ${env:VARIABLE} references rather than literal values.
3. Create the Source, then return to the consequential action and open the argument that needs verification.
4. Enable Ground against a system of record, choose the Source, and define the adapter-specific query, request, or match conditions.
5. Save the rules and run a test action from the connected runtime.

Creating a Source records configuration; it does not make the control plane connect to the customer system. The SDK constructs and calls the Source inside the agent process. Runtime health changes only after a real grounding check has used the Source.

If no Source exists yet, the grounding editor explains this trust boundary and links directly to the Source creation wizard.

Split connection details from verification logic

Put stable connection information on the Source:

sources:
  billing-production:
    adapter: postgres
    host: postgres.internal
    dbname: billing
    user: actionrail_reader
    password: ${env:BILLING_DB_PASSWORD}

Put the question asked for one action argument on the rule:

ground:
  checks:
    - source: billing-production
      query: SELECT customer_id FROM orders WHERE order_id = %(value)s
      match:
        - column: customer_id
          ctx: customer_id

This keeps credentials, endpoints, and transport settings reusable while allowing each tool argument to ask a precise verification question.

MCP is intentionally narrower: a Source names one read-only gateway tool and its argument mapping. Rules reference that Source and define only how to evaluate its returned record.

Naming Sources

Use stable names that communicate system and environment:

billing-production
billing-sandbox
stripe-read-api
support-mcp

Names must start with a letter or number, contain only letters, numbers, hyphens, or underscores, and be unique within the workspace scope. Keep them at 100 characters or fewer.

Do not place hostnames, credentials, customer IDs, or rotating deployment details in a Source name. Rules refer to the name, so renaming it is a configuration migration.

Secrets resolve locally

Source configuration may contain environment references:

headers:
  Authorization: Bearer ${env:BILLING_API_TOKEN}

The Console stores the reference. The SDK replaces it with the environment variable inside the customer’s agent process before building the Source.

Literal authorization secrets are rejected by the Console for HTTP and MCP Sources. Postgres and MySQL passwords must be exactly one ${env:VARIABLE} reference when configured through the Console.

Environment references are not a secret manager

ActionRail resolves references; it does not provision, rotate, or authorize the underlying secret. Use the application’s existing secret manager and give the agent process only the verification credentials it needs.

Least privilege

Every Source identity should be restricted independently of ActionRail rules:

• Postgres, MySQL, and SQLite verification run in query-only/read-only mode;
• HTTP credentials should reach read-only endpoints only;
• MCP gateway credentials should invoke only approved read tools;
• network policy should limit the agent process to required Source endpoints.

Runtime safeguards reduce mistakes. The Source credential and destination system remain the authorization boundary.

Source health

The SDK reports whether a Source completed a grounding check or failed with an error type. The Console aggregates that metadata into Source health, last check time, and referencing agents/rules.

A healthy status means a recent configured check completed. It does not prove every possible query, endpoint, record, or downstream dependency is healthy.