# Connecting to AWS

{% hint style="info" %}
**First time using Bluebricks?** The onboarding wizard walks you through connecting your cloud automatically. Follow the [Quick Start](/docs/getting-started/quick-start.md) instead.
{% endhint %}

## Prerequisites

1. A valid [AWS account](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-creating.html)
2. Permissions to create CloudFormation stacks and IAM roles in your AWS account

## How to connect in the Bluebricks app

{% stepper %}
{% step %}

#### Create a collection and launch CloudFormation

1. Go to the **Collections** page
2. Click **Create Collection**
3. Name the collection (for example, `production` or `staging`)
4. Select **AWS** as the cloud provider
5. In the **Account Number** dropdown, click **New Account**
6. Click **Launch CloudFormation stack**

This opens the AWS CloudFormation console with the Bluebricks template, stack name, and your External ID prefilled.
{% endstep %}

{% step %}

#### Create the stack in AWS

Review the prefilled stack details, scroll to the bottom, acknowledge the IAM capabilities checkbox, and click **Create stack**. Wait for the stack to reach **CREATE\_COMPLETE** status. This usually takes under a minute.
{% endstep %}

{% step %}

#### Copy the Role ARN

Open the **Outputs** tab in the CloudFormation console. The stack provisions IAM roles that Bluebricks uses to access your AWS account. You need at least one Role ARN, but we recommend providing both for full visibility and deployment capabilities.

* **Discovery Role ARN**: grants read-only access for resource discovery, inventory, and the [context layer](/docs/getting-started/building-blocks.md#the-context-layer). Required for the agent to see what is running in your account
* **Orchestration Role ARN**: grants read/write access for deploying and managing infrastructure through [blueprints](/docs/orchestration/packages/blueprints-overview.md). Required for making changes through the orchestration platform

Copy the **Discovery Role ARN** and, if available, the **Orchestration Role ARN**. See [Connect your Cloud](/docs/getting-started/connect-your-cloud.md) for more details on permission types.
{% endstep %}

{% step %}

#### Connect in Bluebricks

Back in the Bluebricks wizard, paste the Role ARN(s) and click **Connect & Create**. Bluebricks verifies the connection and begins ingesting your cloud resources into the context layer.
{% endstep %}
{% endstepper %}

## How to connect via the CLI

You can also connect an AWS cloud account using the Bricks CLI:

```bash
bricks setup aws --collection production
```

The command walks you through the connection flow interactively. After setup completes, verify the connection:

```bash
bricks collection ls
```

A connected collection shows the cloud provider and account name:

```
GUID                                NAME           CLOUD PROVIDER   CLOUD ACCOUNT   SLUG              STATUS
----------------------------------- -------------- ---------------- --------------- ----------------- -------------------------
env-uuid-123                        production    AWS              aws-prod        production        DEFAULT, web-app (running)
```

{% hint style="info" %}
CLI cloud setup currently supports AWS only. To connect GCP, Azure, or a self-hosted runner, use the Bluebricks app with the provider-specific instructions above.
{% endhint %}

## How to connect via the API

Use the [Cloud Accounts API](https://bluebricks.co/docs/api/reference/cloud-accounts) to create a cloud account. Pass the Stack ID as `cloudFormationStackId` and the Role ARN as `roleArnId`.

## Next steps

* [Connect your Cloud](/docs/getting-started/connect-your-cloud.md): overview of all supported providers
* [Connect your Code](/docs/getting-started/connect-your-code.md): give the agent access to your infrastructure repositories


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/getting-started/connect-your-cloud/how-to-connect-aws.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.