> For the complete documentation index, see [llms.txt](https://copilot-docs.bugbase.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-cloud-assessment/provider-runbooks.md).

# Set Up the Cloud Agent

Prepare a cloud VM and attached identity, install the Pentest Copilot agent, and grant the required provider role.

Complete [Cloud Assessment Prerequisites](/enterprise/how-to-trigger-a-cloud-assessment/configure-a-cloud-agent.md) before preparing the agent VM.

## 1. Prepare the VM and Identity

You can use an existing VM and attached cloud identity or create them for the assessment. Existing infrastructure must be inside the approved cloud scope and meet the same identity, metadata, network, and operating system requirements.

| Provider     | Setup                                                                                                                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AWS          | Use an EC2 instance in the approved account and region. Verify its instance profile contains the approved IAM role, attaching one if needed, and require IMDSv2.                            |
| Azure        | Use an Azure VM in the approved subscription and resource group. Verify its system-assigned or approved user-assigned managed identity, enabling or attaching one if needed.                |
| Google Cloud | Use a Compute Engine VM in the approved project. Verify its approved service account, attaching one if needed, and use the `cloud-platform` VM access scope when active testing is planned. |

Confirm the VM can reach Pentest Copilot, cloud provider APIs, and the provider metadata service.

The agent uses only the identity supplied through native VM metadata. Do not configure static cloud credentials or local CLI profiles for the agent.

## 2. Install the Agent

1. Open **Settings -> Agent** in Pentest Copilot.
2. Generate the launcher for the VM operating system.
3. Run the launcher on the cloud VM.
4. Confirm the new agent appears as connected in **Dashboard -> Agents** or **Settings -> Agent**.
5. Confirm the displayed host and network details match the VM.

Keep the launcher and bootstrap token out of shell history, tickets, and shared documents. Do not assign an agent ID manually.

{% hint style="info" %}
The agent can connect and run capabilities that do not call provider APIs without a cloud read role. Cloud discovery will be incomplete or fail until read permissions are granted.
{% endhint %}

## 3. Grant Cloud Permissions

Use a standard provider role for the simplest setup:

| Provider     | Discovery                                                                                                                      | Full active scan in an isolated test environment                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| AWS          | [`ReadOnlyAccess`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ReadOnlyAccess.html)                        | [`AdministratorAccess`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html)                   |
| Azure        | [`Reader`](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles/general#reader) at the VM resource group | [`Owner`](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles/privileged#owner) inside the approved boundary |
| Google Cloud | [`Viewer` (`roles/viewer`)](https://cloud.google.com/iam/docs/roles-overview#basic) at the project                             | [`Owner` (`roles/owner`)](https://cloud.google.com/iam/docs/roles-overview#basic) at the approved project                           |

Administrator-equivalent roles are not required for installation or discovery. Use them only when broad active testing is authorized in an isolated environment, and remove them after cleanup. With narrower permissions, the assessment still runs but only authorized checks supported by the attached identity can complete.

For custom roles, provider data-plane access, and the exact discovery actions, see [Cloud Permissions](/enterprise/cloud-assessment-reference/cloud-permissions-reference.md).

## 4. Verify the Setup

Before discovery, confirm:

* the agent is connected;
* the attached identity matches the approved identity;
* the discovery role is assigned;
* AWS prefixes, Azure resource group, or Google Cloud project match the approved scope;
* required provider APIs are enabled.

Return to [Run a Cloud Assessment](/enterprise/how-to-trigger-a-cloud-assessment.md) and start cloud discovery.