Docs/Reference

Configuration file

Every project has a synchronoid.yaml file at its root. It names the project, sets defaults and declares sources, feeds, channels and alert rules. Python code defines the logic, and the file defines how it runs.

Annotated example

synchronoid.yaml

project: registry-sync
workspace: acme-data
region: eu-frankfurt            # eu-frankfurt or us-virginia. Cannot be changed later.
modules: [pipelines]         # Python packages that contain assets and pipelines

defaults:
  retry:
    max_attempts: 3
    backoff: exponential
  timeout: "1h"
  max_concurrency: 8

environments:
  dev:  { retention_days: 7 }
  prod: { retention_days: 90 }

sources:
  company_registry:
    connector: http_json
    base_url: https://registry.example.org/api
    auth: { type: bearer, token: ${secret:REGISTRY_API_KEY} }
    rate_limit: { per_minute: 120, reserve: 0.2 }
    auto_pause: { after_failures: 10, window: "30m" }

feeds:
  crm-sync:
    events: ["company.*"]
    webhook: { url: https://example.com/hooks/synchronoid }

channels:
  data-alerts: { type: slack, webhook_url: ${secret:SLACK_WEBHOOK} }

alerts:
  run-failed: { when: run.failed, severity: high, channels: [data-alerts] }

Top-level keys

Key	Type	Required	Description
`project`	string	Yes	Project name. Lowercase letters, digits and dashes.
`workspace`	string	Yes	Workspace that receives deploys.
`region`	string	No	Data region. Default: the region of the workspace.
`modules`	list	Yes	Python packages with your assets and pipelines.
`defaults`	map	No	Defaults for retry, timeout and concurrency.
`environments`	map	No	Per-environment overrides.
`sources`	map	No	Sources by name.
`feeds`	map	No	Change feed subscriptions.
`destinations`	map	No	Warehouses that receive published assets, such as Snowflake or BigQuery. See Snowflake.
`transformations`	map	No	Transformation projects that run after assets, such as dbt. See dbt.
`insights`	map	No	Cost insights settings (preview), such as `cost.enabled` and `cost.window_days`.
`channels`	map	No	Alert destinations.
`alerts`	map	No	Alert rules.

sources

Key	Description
`connector`	Connector type, such as `http_json`, `postgresql`, `sftp_csv` or `graphql`. Required.
`base_url`, `dsn`	Where to connect, depending on the connector.
`auth`	`type` (`bearer`, `basic`, `header`, `oauth2`) and its values.
`rate_limit`	Same options as `sy.RateLimit`. See Rate limits.
`auto_pause`	`after_failures`, `window`, `notify`.
`retry`	Default retry policy for assets that read from this source. Same options as `sy.Retry`.
other keys	Connector-specific options, such as `host`, `bucket` or `paging`, passed as they are. Each integration page lists them.

A source declared in YAML and a sy.Source with the same name in Python are merged. Values in YAML win. See Sources and connectors.

Referencing secrets and environment values

Use ${secret:NAME} for secrets, and ${env:NAME} for non-secret values defined in the environment. Unknown names stop the run with SYN-3012. See Secrets.

Environment overrides

Any key under environments.NAME.overrides replaces the same path in the base file when the project runs in that environment.

synchronoid.yaml

environments:
  dev:
    overrides:
      sources.company_registry.base_url: https://sandbox.registry.example.org/api
      sources.company_registry.rate_limit.per_minute: 20

Validation

Run syn deploy --dry-run or syn doctor to validate the file. The checks include:

Unknown keys are errors, so a typo does not silently do nothing.
Every channel used by a rule must exist.
Strings that look like live tokens are rejected.
The region can only be set when the project is created.

Python or YAML?Keep structure that changes rarely, such as sources and alerts, in YAML. Keep logic and anything that depends on code, such as partitions and event rules, in Python.