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

# Install Diffblue Agents

> Download and install Diffblue Agents

## Prerequisites

Verify that you meet the [system requirements](/system-requirements) before proceeding.

## Install

<Tabs>
  <Tab title="macOS (Apple Silicon)">
    ```bash theme={null}
    curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh | sh
    ```
  </Tab>

  <Tab title="macOS (Intel)">
    ```bash theme={null}
    curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh | sh
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh | sh
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    irm https://release.diffblue.com/diffblue-agents/install.ps1 | iex
    ```
  </Tab>
</Tabs>

The install script downloads the latest release for your platform, extracts it to `~/.diffblue/agents/` (`%USERPROFILE%\.diffblue\agents` on Windows), and adds it to your `PATH`.

To reinstall or update, run the same command again: the script will replace the existing installation.

If the Diffblue Agents server is running, stop it before reinstalling with `diffblue-agents --stop-server` from your project directory.

To verify, navigate to your project directory and run:

```bash theme={null}
diffblue-agents version
```

<Accordion title="Installation customization">
  To pass options, download and run the script directly instead of piping it:

  <Tabs>
    <Tab title="macOS (Apple Silicon)">
      ```bash theme={null}
      curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh -o install.sh
      sh install.sh --force --install-dir /opt/diffblue-agents
      ```
    </Tab>

    <Tab title="macOS (Intel)">
      ```bash theme={null}
      curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh -o install.sh
      sh install.sh --force --install-dir /opt/diffblue-agents
      ```
    </Tab>

    <Tab title="Linux">
      ```bash theme={null}
      curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh -o install.sh
      sh install.sh --force --install-dir /opt/diffblue-agents
      ```
    </Tab>

    <Tab title="Windows">
      ```powershell theme={null}
      & ([scriptblock]::Create((irm https://release.diffblue.com/diffblue-agents/install.ps1))) -Force -InstallDir C:\diffblue-agents
      ```
    </Tab>
  </Tabs>

  | Option                   | Shell                  | PowerShell           | Description                                                        |
  | ------------------------ | ---------------------- | -------------------- | ------------------------------------------------------------------ |
  | Custom install directory | `--install-dir <path>` | `-InstallDir <path>` | Install to a custom directory instead of `~/.diffblue/agents/`     |
  | Skip PATH modification   | `--no-modify-path`     | `-NoModifyPath`      | Do not add the `cli` directory to your `PATH`                      |
  | Force                    | `--force`              | `-Force`             | Stop a running server before overwriting the existing installation |
</Accordion>

You can also [install manually](#manual-install) by downloading and extracting the archive yourself.

## Configure your AI coding agent

Diffblue Agents uses Claude Code by default. To select a different [supported AI coding agent platform](/system-requirements#supported-ai-coding-agent-platforms) or provide a custom path, use the `install` command.

### Interactive configuration

Run the install command without arguments to select your agent interactively:

```bash theme={null}
diffblue-agents install
```

The install command scans your `PATH` for supported agents and presents an interactive selection menu. If your agent is not detected automatically, select "Enter path manually" to specify the agent type and executable path.

The install command saves your selection and then validates that the selected agent works correctly by running a test prompt, which may take up to 60 seconds. If validation fails, you may need to rerun the install command to correct the saved path.

### Non-interactive configuration

To configure an agent without using the interactive selection menu, specify the agent type and path directly:

```bash theme={null}
diffblue-agents install agent <agent-type> <path-to-agent>
```

Replace `<agent-type>` with `claude` or `copilot`, and `<path-to-agent>` with the absolute path to the agent executable.

**Example:**

```bash theme={null}
diffblue-agents install agent claude /usr/local/bin/claude
```

This mode is useful for automated setup or CI/CD pipelines.

### Configuration options

See the [CLI reference](/reference/cli#environment-variables) for all configuration options, including environment variables for agent platform selection and custom paths.

## Manual install

1. Download the archive for your platform:

   <Tabs>
     <Tab title="macOS (Apple Silicon)">
       ```bash theme={null}
       curl -JLO https://release.diffblue.com/diffblue-agents/latest-macos_aarch64
       ```
     </Tab>

     <Tab title="macOS (Intel)">
       ```bash theme={null}
       curl -JLO https://release.diffblue.com/diffblue-agents/latest-macos_amd64
       ```
     </Tab>

     <Tab title="Linux">
       ```bash theme={null}
       curl -JLO https://release.diffblue.com/diffblue-agents/latest-linux
       ```
     </Tab>

     <Tab title="Windows">
       ```powershell theme={null}
       curl.exe -JLO https://release.diffblue.com/diffblue-agents/latest-windows
       ```
     </Tab>
   </Tabs>

2. Extract the archive:

   <Tabs>
     <Tab title="macOS (Apple Silicon)">
       ```bash theme={null}
       unzip diffblue-agents-*.zip
       ```
     </Tab>

     <Tab title="macOS (Intel)">
       ```bash theme={null}
       unzip diffblue-agents-*.zip
       ```
     </Tab>

     <Tab title="Linux">
       ```bash theme={null}
       unzip diffblue-agents-*.zip
       ```
     </Tab>

     <Tab title="Windows">
       ```powershell theme={null}
       Expand-Archive diffblue-agents-*.zip .
       ```
     </Tab>
   </Tabs>

3. Add the `cli` directory to your `PATH` or create an alias. Replace `X.X.X` with the version you installed.

   <Tabs>
     <Tab title="macOS (Apple Silicon)">
       ```bash theme={null}
       # add the cli directory to your PATH:
       echo 'export PATH="$HOME/diffblue-agents-X.X.X-macos_aarch64/cli:$PATH"' >> ~/.zshrc
       source ~/.zshrc

       # or, create an alias:
       echo 'alias diffblue-agents="$HOME/diffblue-agents-X.X.X-macos_aarch64/cli/diffblue-agents"' >> ~/.zshrc
       source ~/.zshrc
       ```
     </Tab>

     <Tab title="macOS (Intel)">
       ```bash theme={null}
       # add the cli directory to your PATH:
       echo 'export PATH="$HOME/diffblue-agents-X.X.X-macos_amd64/cli:$PATH"' >> ~/.zshrc
       source ~/.zshrc

       # or, create an alias:
       echo 'alias diffblue-agents="$HOME/diffblue-agents-X.X.X-macos_amd64/cli/diffblue-agents"' >> ~/.zshrc
       source ~/.zshrc
       ```
     </Tab>

     <Tab title="Linux">
       ```bash theme={null}
       # add the cli directory to your PATH:
       echo 'export PATH="$HOME/diffblue-agents-X.X.X-linux_amd64/cli:$PATH"' >> ~/.bashrc
       source ~/.bashrc

       # or, create an alias:
       echo 'alias diffblue-agents="$HOME/diffblue-agents-X.X.X-linux_amd64/cli/diffblue-agents"' >> ~/.bashrc
       source ~/.bashrc
       ```
     </Tab>

     <Tab title="Windows">
       ```powershell theme={null}
       # add the cli directory to your PATH:
       [Environment]::SetEnvironmentVariable("PATH", "$HOME\diffblue-agents-X.X.X-windows_amd64\cli;$([Environment]::GetEnvironmentVariable("PATH", "User"))", "User")

       # or, create an alias:
       Set-Alias diffblue-agents "$HOME\diffblue-agents-X.X.X-windows_amd64\cli\diffblue-agents.ps1"
       ```
     </Tab>
   </Tabs>

4. Verify the installation:

   ```bash theme={null}
   diffblue-agents version
   ```

## Troubleshooting

<AccordionGroup>
  <Accordion title="macOS: remove quarantine attribute">
    macOS may quarantine files downloaded from the internet. If you see a warning that the file is from an unidentified developer, remove the quarantine attribute from the extracted directory:

    ```bash theme={null}
    # Apple Silicon
    xattr -r -d com.apple.quarantine diffblue-agents-X.X.X-macos_aarch64/

    # Intel
    xattr -r -d com.apple.quarantine diffblue-agents-X.X.X-macos_amd64/
    ```
  </Accordion>

  <Accordion title="Windows: scripts blocked from executing">
    Windows may block downloaded scripts from executing. In PowerShell, navigate into the Diffblue Agents installation directory and run:

    ```powershell theme={null}
    Unblock-File cli\diffblue-agents.ps1
    Unblock-File server\diffblue-agents-server.ps1
    Unblock-File jre\bin\java.exe
    ```

    If the scripts still fail to execute after unblocking, set your PowerShell execution policy to RemoteSigned for the current user:

    ```powershell theme={null}
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
    ```

    Then restart your terminal.
  </Accordion>
</AccordionGroup>

## Next steps

* [Quickstart](/quickstart) — activate your license and run your first workflow.