syndai.yaml

syndai.yaml is a file you commit to your repo. It sets policy for every run on that repo, so you do not have to send the same policy_config each time. You do not need it to use the API.

Where it lives

Syndai looks for the file in two places, in this order:

1. syndai.yaml at the repo root
2. .syndai/workflow.yaml

It reads only the first one it finds. The file can be at most 64 KB.

Syndai reads it from the repo as checked out when the run starts, before the agent changes anything. So a run that edits syndai.yaml does not change its own policy. The next run reads the new file once it is merged.

What wins

When the same key is set in more than one place, the one further right wins:

Syndai defaults < saved defaults < syndai.yaml < policy_config on the run

Saved defaults are the ones you set for the workspace or a project, in the app or with PUT /policy/defaults. Keys you leave out of the file keep the value from the layer below.

A few keys keep the value the run already had, whatever the file says. The run's sandbox is set up before the file is read. Anyone who can merge a change can also edit the file. So these keys are not taken from it:

• egress.profile
• budget.branch_strategy
• budget.max_budget_usd
• autonomy
• tools.builtins and tools.disabled_builtin_capabilities, once a layer below has set them

Set these on the run, or in your saved defaults.

An example

This repo's own file is a real one. Here is a smaller example:

# syndai.yaml
version: 1

default_policy:
  validation:
    level: standard          # smoke, standard or strict
    timeout_seconds: 600     # cap for each check command, in seconds

    # Folders that hold templates you ship elsewhere.
    # Syndai never builds or tests inside them.
    template_trees:
      - tools/scaffold

    # What each check folder reads. See "validation.inputs" below.
    inputs:
      api:
        - api/
        - shared/
        - Makefile
      apps/web:
        - apps/web/
        - packages/
        - package.json
        - pnpm-lock.yaml

  reviews:
    required_gates:
      - adversarial_review

  budget:
    retry_budget: 3          # how many times a failed check may be fixed and run again

  artifacts:
    retention_profile: standard   # standard, extended or pinned

  context_research_enabled: true

Top-level keys

key	what it does
version	must be 1; you can leave it out
default_policy	policy for every run on this repo, in the same shape as policy_config
validation	a short form; it is merged into default_policy.validation
review_gates	a short form; each name is added to default_policy.reviews.required_gates
test_login	how checks sign in to your app; see Test logins

Any other top-level key makes the file invalid.

default_policy

This takes the same fields as policy_config on a run. Policy lists every field. The ones people set here most:

key	values
validation.profile	auto, python, nextjs, vite, flutter, react_native, native_ios, native_android
validation.level	smoke, standard, strict
validation.base_freshness	as_of_base, latest_main
validation.timeout_seconds	a whole number above zero
validation.template_trees	a list of folders; see below
validation.inputs	a map of folder to paths; see below
reviews.required_gates	gates to add; see Review gates
budget.retry_budget	a whole number, zero or more
artifacts.retention_profile	standard, extended, pinned
context_research_enabled	true or false

Some validation keys are never accepted, here or on a run. These are commands, execution_environment, github_workflow_id, github_result_artifact_name and artifact_upload. Syndai works out the check commands itself. See Validation.

validation.template_trees

These are folders of files you ship as data, like starter kits you copy into other repos. They are not parts of this repo. Syndai never plans builds or tests inside them.

Each entry is a plain path from the repo root, like tools/scaffold. It has no slash at the start or end, and no . or .. part. You can list up to 50, with no repeats.

validation.inputs

This lists every path that a folder's checks read. Use it when a folder's checks read files outside that folder. Two common cases: a backend test suite that loads a shared schema, or a web app that builds from shared packages.

default_policy:
  validation:
    inputs:
      api: [api/, shared/, Makefile]

How it works:

• Keys are the folders the checks run in, as Syndai's check plan names them, like api or apps/web. Use . for the repo root.
• Values are paths from the repo root. They match whole path parts. So shared/ covers shared/x.ts, and Makefile covers only Makefile. A / at the end is optional. . means the whole repo.
• No wildcards. The characters *, ?, [, ], \ and : are refused.
• Each list needs 1 to 50 entries, with no repeats. You can list up to 50 folders.
• The folder itself always counts as an input, even if you leave it out.

What it changes:

• Skipping. A check runs only when the run's change touches one of its inputs. With no entry for a folder, its checks run when the change touches that folder. They also run when it touches a root manifest or lock file, or anything under packages/.
• Reuse. A check may have passed earlier in the run. Later, its inputs, command and environment may all be the same. Then Syndai keeps that pass and does not run the command again. With no entry for a folder, a pass is kept only when the whole repo is unchanged.

List every path a folder's checks read. If you leave one out, it can change and the check will not run again.

review_gates

A short way to add gates:

review_gates:
  - adversarial_review

Each name is added to reviews.required_gates. The gates planning_review, security_review and preflight are always required, with or without this list.

When the file is broken

The run fails before the agent starts if the file:

• is not valid YAML, or its top level is not a map;
• is larger than 64 KB;
• has a version other than 1;
• has a top-level key not listed above.

The run's failure reason is invalid_policy, and the message names the file and the problem.

What it cannot do

• Turn off the three required review gates.
• Change the network profile, branch strategy, spend cap or autonomy of a run.
• Set check commands or a GitHub workflow to run.
• Pick webhook events. Each endpoint picks its own with event_types; see Webhooks.