Nx Cloud introduces a new `.nx/ci-config.yaml` file that centralizes pipeline configuration, replacing the flag-heavy `nx-cloud start-ci-run` command with a simpler `npx nx-cloud start-nx-agents`. The old approach required passing all settings as CLI flags on a single command that had to run first in the pipeline — creating order-dependency issues across parallel CI jobs. The new config file is read by every Nx Cloud command, eliminating ordering requirements. It has four optional sections: `lifecycle`, `dte`, `nx-agents`, and `overrides`. New capabilities include dynamic agent allocation via changeset size, inline assignment rules, and per-environment overrides without duplicating flag strings. Migration is straightforward: copy the generated YAML from the Nx Cloud UI's Config YAML page into `.nx/ci-config.yaml` and replace `start-ci-run` with `start-nx-agents` in one commit — the two cannot coexist.
Table of contents
Why a centralized config fileConfiguration that doesn't depend on command orderWhat goes in the fileSeeing the config a run actually usedAdditional improvements to previously used flagsMigratingWhy this shapeGet startedLearn moreQuestions this post answers
What is the difference between nx-cloud start-ci-run and start-nx-agents?
`start-nx-agents` replaces `start-ci-run` and reads all configuration from `.nx/ci-config.yaml` instead of CLI flags. Unlike `start-ci-run`, it does not need to be the first Nx command in the pipeline — every Nx Cloud command reads the config file when it runs, removing the order-dependency problem that caused competing configurations across parallel CI jobs. `start-ci-run` exits with an error if `.nx/ci-config.yaml` exists. Teams migrating Nx monorepo pipelines track breaking command changes like this on daily.dev.
How do I migrate from nx-cloud start-ci-run flags to the new ci-config.yaml format?
Open the Configuration section of your most recent CIPE in Nx Cloud, go to the Config YAML page, and copy the generated YAML into `.nx/ci-config.yaml` in your repo. Then replace `start-ci-run` with `start-nx-agents` in your workflow file. Both changes must happen in the same commit — there is no gradual rollout where both coexist, as `start-ci-run` exits with an error when the config file is present. Developers shipping this migration in monorepos find the full flag-to-key mapping covered on daily.dev.
How do I configure different Nx Cloud agent counts for small vs large PRs?
Use a map under `dte.distribute-on` in `.nx/ci-config.yaml`, keyed by changeset size. For example: `small-changeset: 3 linux-medium`, `medium-changeset: 6 linux-large`, `large-changeset: 10 linux-large`. This replaces the previous approach of passing a single launch-template string and enables dynamic agent allocation based on the size of the changeset being processed. Nx monorepo cost and speed tuning topics like this surface regularly on daily.dev.
3K Impressions1 Comment