> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nrwl/nx/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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:

```yaml theme={null}
# .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.

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

  ```bash theme={null}
  npx nx g ci-workflow
  ```
</Note>

## How Nx Agents work

<CardGroup cols={2}>
  <Card title="Declarative configuration" icon="file-code">
    You specify the number and type of agents. Nx Cloud distributes tasks automatically — no manual assignment required as your codebase grows.
  </Card>

  <Card title="Task-centric scheduling" icon="list-check">
    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.
  </Card>

  <Card title="Remote cache as transport" icon="cloud">
    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.
  </Card>

  <Card title="Dynamic agent allocation" icon="sliders">
    Allocate more or fewer agents depending on PR size. Only large PRs that need the compute pay for it.
  </Card>
</CardGroup>

## Affected detection in CI

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

```bash theme={null}
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:

```bash theme={null}
# For Cypress
nx add @nx/cypress

# For Playwright
nx add @nx/playwright
```

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

```yaml theme={null}
- 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](/features/cache-task-results) for configuration details.