Skip to main content
The Relay is configured entirely through a single YAML file, typically named relay-config.yaml. You pass its path to the container at startup by mounting it at /app/relay-config.yaml.

​
Environment variable substitution

Any value in the configuration file can reference an environment variable using ${VAR_NAME} syntax: 
connection:
  host: ${PG_HOST}
  password: ${PG_PASSWORD}
This keeps secrets out of the config file. Set the environment variables in your container runtime (Docker -e flags, Kubernetes Secrets, ECS task definition secrets, etc.).

​
controlPlane

Connection settings for the CauseFlow control plane. 
controlPlane:
  url: wss://api.causeflow.ai/v1/relay/connect
  token: ${RELAY_TOKEN}
  tenantId: ${TENANT_ID}
FieldTypeRequiredDescription
urlstringYesThe WebSocket endpoint for the control plane. Always wss://api.causeflow.ai/v1/relay/connect unless directed otherwise by support.
tokenstringYesYour relay authentication token. Obtain from Dashboard → Settings → Relay. Use ${RELAY_TOKEN} and pass the value as an environment variable.
tenantIdstringYesYour CauseFlow tenant ID. Found in Dashboard → Settings → General.

​
resources

An array of database resources the Relay can access. Each resource has a unique ID and its own connection, operation, and row limit settings. 
resources:
  - id: main-pg
    type: postgres
    name: Main PostgreSQL
    connection:
      host: ${PG_HOST}
      port: 5432
      database: ${PG_DATABASE}
      user: ${PG_USER}
      password: ${PG_PASSWORD}
    allowedOperations: [query, describe_table, list_tables, explain]
    maxRowsPerQuery: 1000

​
Resource fields

FieldTypeRequiredDescription
idstringYesA unique identifier for this resource within your tenant. Used in query requests to identify the target database. Use lowercase with hyphens (e.g., main-pg, analytics-mongo).
typestringYesDatabase type. Accepted values: postgres, mongodb.
namestringYesA human-readable display name shown in the CauseFlow Dashboard.
connectionobjectYesType-specific connection parameters. See below.
allowedOperationsarrayYesOperations permitted on this resource. See allowed operations.
maxRowsPerQueryintegerNoMaximum rows returned per query. Requests exceeding this limit are clamped, not rejected. Default: 1000.

​
PostgreSQL connection

connection:
  host: ${PG_HOST}
  port: 5432
  database: ${PG_DATABASE}
  user: ${PG_USER}
  password: ${PG_PASSWORD}
FieldTypeRequiredDescription
hoststringYesHostname or IP address of the PostgreSQL server.
portintegerNoPostgreSQL port. Default: 5432.
databasestringYesDatabase name to connect to.
userstringYesPostgreSQL user. This user must have at least SELECT privilege on the tables you want to query.
passwordstringYesPassword for the PostgreSQL user. Use ${VAR} syntax.
The Relay maintains a connection pool with a maximum of 5 connections, 30-second idle timeout, and 10-second connect timeout. All queries run inside READ ONLY transactions with a 30-second statement timeout.

​
MongoDB connection

connection:
  uri: ${MONGO_URI}
  database: ${MONGO_DATABASE}
FieldTypeRequiredDescription
uristringYesFull MongoDB connection URI (e.g., mongodb://user:pass@host:27017). Use ${VAR} syntax for the URI or embed credentials via separate variables.
databasestringYesDatabase name to use for queries.

​
Allowed operations

The allowedOperations array controls which query types the policy engine permits for a resource. The valid values are:
OperationDescription
queryExecute a SELECT query (PostgreSQL) or a find operation (MongoDB).
describe_tableReturn column names, types, and metadata for a specific table or collection.
list_tablesList all tables or collections in the database.
explainReturn the query execution plan without executing the query.
For most use cases, include all four operations. Restricting to query and describe_table is useful if you want to prevent AI agents from enumerating your full schema.

​
masking

Controls PII masking applied to query results before they leave your network. 
masking:
  enabled: true
  patterns:
    - name: cpf
      regex: '\d{3}\.\d{3}\.\d{3}-\d{2}'
      replacement: '***.***.***-**'
    - name: email
      regex: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      replacement: '***@***.***'
FieldTypeRequiredDescription
enabledbooleanYesWhether to apply masking to query results. Set to false to disable. Note: disabling masking does not disable the read-only policy or SQL validation.
patternsarrayNoCustom masking patterns in addition to (or instead of) built-in patterns.

​
Pattern fields

FieldTypeRequiredDescription
namestringYesA unique name for this pattern. Used in audit log entries.
regexstringYesA regular expression to match against field values. Escape backslashes in YAML strings (use \\d for \d, or use single quotes).
replacementstringYesThe string to substitute for any match.
Built-in patterns (CPF, email, credit card, phone, bearer token) are always active when masking.enabled is true. Custom patterns are applied in addition to built-in patterns. See PII masking for the full list of built-in patterns and examples.

​
audit

Controls structured JSON audit logging. 
audit:
  enabled: true
  level: info
FieldTypeRequiredDescription
enabledbooleanYesWhether to write audit log entries.
levelstringNoLog verbosity. Accepted values: debug, info, warn, error. Default: info. Use debug during troubleshooting and info in production.
Audit logs are written to stdout and include: timestamp, log level, request ID, resource ID, operation, row count, masked field count, execution time in milliseconds, and outcome. Query parameters and row values are never written to the log.

​
Complete example

relay-config.yaml
controlPlane:
  url: wss://api.causeflow.ai/v1/relay/connect
  token: ${RELAY_TOKEN}
  tenantId: ${TENANT_ID}

resources:
  - id: main-pg
    type: postgres
    name: Main PostgreSQL
    connection:
      host: ${PG_HOST}
      port: 5432
      database: ${PG_DATABASE}
      user: ${PG_USER}
      password: ${PG_PASSWORD}
    allowedOperations: [query, describe_table, list_tables, explain]
    maxRowsPerQuery: 1000

  - id: analytics-mongo
    type: mongodb
    name: Analytics MongoDB
    connection:
      uri: ${MONGO_URI}
      database: ${MONGO_DATABASE}
    allowedOperations: [query, describe_table, list_tables]
    maxRowsPerQuery: 500

masking:
  enabled: true
  patterns:
    - name: cpf
      regex: '\d{3}\.\d{3}\.\d{3}-\d{2}'
      replacement: '***.***.***-**'
    - name: email
      regex: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      replacement: '***@***.***'
    - name: internal-id
      regex: 'EMP-\d{6}'
      replacement: 'EMP-******'

audit:
  enabled: true
  level: info