CI Orchestration

Distribute task execution across multiple CI machines with Nx Agents. Combine affected detection, remote caching, and dynamic agent allocation for fast, scalable CI.

Nx Cloud adopts a task-based CI model that overcomes the slowness and unreliability of traditional VM-based CI. Instead of statically assigning work to machines, Nx Cloud dynamically distributes individual tasks across available agents — optimizing for speed and resource utilization.

Teams using Nx Cloud report:

• 30–70% faster CI pipelines
• 40–75% reduction in CI compute costs
• Improved reliability through automatic flaky task detection and retries

Connect to Nx Cloud

npx nx@latest connect

This connects your workspace to Nx Cloud and enables remote caching and all CI features.

Nx Agents: distributed task execution

Nx Agents distribute your tasks across multiple CI machines automatically. You declare how many agents you want; Nx Cloud handles scheduling, dependency ordering, and artifact transfer.

Enable Nx Agents in your CI pipeline

Add the start-ci-run command to your CI configuration:

# .github/workflows/ci.yml
name: CI

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          filter: tree:0

      - run: pnpm dlx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      - uses: nrwl/nx-set-shas@v4

      - run: pnpm exec nx affected -t lint test build

The --distribute-on="3 linux-medium-js" argument tells Nx Cloud to spin up 3 agents using the linux-medium-js launch template. All nx commands issued in the pipeline are collected and distributed across those agents automatically.

Generate a pre-configured CI workflow for your provider with:

npx nx g ci-workflow

How Nx Agents work

Declarative configuration

You specify the number and type of agents. Nx Cloud distributes tasks automatically — no manual assignment required as your codebase grows.

Task-centric scheduling

Tasks are dispatched based on historical run times and dependency ordering from the Nx project graph. If an agent fails to start, other agents pick up its work.

Remote cache as transport

Nx Replay (remote caching) is used to transfer build artifacts between agents, ensuring each task runs only once and its outputs are available wherever needed.

Dynamic agent allocation

Allocate more or fewer agents depending on PR size. Only large PRs that need the compute pay for it.

Affected detection in CI

Combine nx affected with Nx Agents so that only changed projects run tasks, and those tasks are distributed across machines:

pnpm exec nx affected -t lint test build

When used together with the start-ci-run command, affected detection and distributed execution work simultaneously — Nx determines the minimal set of tasks, then distributes them across agents.

Automatic E2E test splitting

Large e2e test suites can be split into per-file tasks and distributed across agents using the Nx Atomizer. Enable it by adding the appropriate plugin:

# For Cypress
nx add @nx/cypress

# For Playwright
nx add @nx/playwright

Then run the -ci variant of your e2e target in CI:

- run: pnpm exec nx affected -t lint test build e2e-ci

Each spec file becomes an independent task that can run on a separate agent, turning a 10-minute e2e suite into multiple 2-minute parallel tasks.

Remote caching in CI

Nx Replay (remote caching) is enabled automatically when you connect to Nx Cloud. In CI:

• Tasks completed in a previous run are replayed from cache — no re-execution
• Cache is shared between agents in the same run
• Developers can pull cache results from CI to their local machines

See Cache Task Results for configuration details.