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

# Agents

The **Agents** tab lists every machine connected to a grid and lets you manage what each one does.
Open a grid from **Self-hosted grids**, then select **Agents**.

<Note>
  Agent management requires **Admin** permission and the **Grid** to be **online** and running
  Incredibuild **10.36.0** or later - viewers see everything read-only. Some sections appear only on
  **Windows** grids.
</Note>

## The agents list

Each row shows the agent's **status**, **name**, **role**, **build group**, and when it was **last
connected**. Hover an agent to open its details popover - **hostname**, **IP** (with copy), **CPU
usage**, **RAM usage**, and **OS version**.

| Status                                  | Meaning                         |
| --------------------------------------- | ------------------------------- |
| **Online** / **Working** / **Updating** | Connected and available (green) |
| **Offline** / **Expired**               | Not currently usable (grey)     |

<Note>When the grid is offline, agent details may be outdated until it reconnects.</Note>

## Add an agent

<Steps>
  <Step title="Open the dialog">
    Click **Add agent**. A ready-to-run install command is generated for your grid (it appears once
    the grid is connected).
  </Step>

  <Step title="Copy the command">
    Copy the generated command:

    <Tabs>
      <Tab title="Windows">
        ```bat theme={null}
        curl -k -o "%temp%\silent-installer.exe" "https://<your-coordinator>:8000/setup/silent-installer" && start /wait "" "%temp%\silent-installer.exe" /silent_installer /install /COORDINATOR=<your-coordinator> /COMPONENTS=[Agent]
        ```
      </Tab>

      <Tab title="Linux">
        ```bash theme={null}
        IB_INSTALLER=$(mktemp --suffix=.run) && curl -fSL -o "$IB_INSTALLER" 'https://downloads.incredibuild.com/incredibuild_4.29.1.run' && chmod +x "$IB_INSTALLER" && sudo "$IB_INSTALLER" --action install --initiator enabled --helper enabled --data-dir '/incredibuild/' --coordinator-machine '<your-coordinator>'
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Run it on each machine">
    Run the command on every machine you want to join the grid as a helper agent. Agents appear in the
    list once they connect.
  </Step>
</Steps>

## Manage an agent

Use the controls on each row:

* **Rename** - click the agent's name to edit it inline.
* **Role** - click the role to assign **Helper**, **Initiator**, **CI Initiator**, or **Build Cache**,
  set each as **Fixed** or **Floating**, and allocate cores.
* **Build group** - assign the agent to a build group. You can also create, rename, or delete groups,
  and toggle whether cloud agents can assist builds from a group.
* **Build log level** - Minimal, Basic, Intermediate, Extended, or Detailed.
* **Build priority** - Highest, High, Normal, Low, or Lowest.

### Bulk changes

Select multiple online agents to apply a single change - **agent name**, **role**, **build group**,
**log level**, or **build priority** - to all of them at once.

## Roles

| Role             | What it does                                            |
| ---------------- | ------------------------------------------------------- |
| **Helper**       | Contributes cores to accelerate other machines' builds. |
| **Initiator**    | Starts and distributes builds.                          |
| **CI Initiator** | An initiator for CI machines.                           |
| **Build Cache**  | Provides a local build cache.                           |

**Fixed** vs **Floating** determines how the role's license cores are allocated. The **license
summary** at the top of the page shows how many Helper cores, Initiators, CI initiators, and Build
Cache cores are assigned, available, and in the pool.