# Quick Start

This guide gets you from sign-up to your first conversation with the Bluebricks agent. By the end, you will have connected a cloud account and your code, and asked the agent a real question about your infrastructure.

For a broader overview of the platform before diving in, see [What is Bluebricks?](/docs/getting-started/building-blocks.md).

## What you need

* A Bluebricks account. Sign up at [app.bluebricks.co](https://app.bluebricks.co) if you have not already
* An AWS or Azure cloud account with permissions to create IAM roles or register applications
* A GitHub organization with infrastructure code repositories (optional; you can skip this step and connect code later)

The onboarding wizard walks you through the steps below.

## 1. Connect your cloud

The first step is to connect a cloud account so Bluebricks can discover what is running in your environment.

1. Name your cloud account and pick a color to identify it
2. Select your cloud provider: **AWS** or **Azure** (GCP coming soon)
3. Follow the provider-specific setup to grant Bluebricks read access to your account

{% tabs %}
{% tab title="AWS" %}
Bluebricks uses a CloudFormation stack to provision an IAM role in your AWS account.

1. Click **Launch CloudFormation stack** in the onboarding wizard. This opens the AWS CloudFormation console with the Bluebricks template, stack name, and your External ID prefilled
2. In AWS, acknowledge the IAM capabilities and click **Create stack**
3. Once the stack completes, copy the **Discovery Role ARN** from the stack's **Outputs** tab
4. Paste the Role ARN back into the Bluebricks wizard and click **Connect**

For the full walkthrough, see [Connecting to AWS](/docs/getting-started/connect-your-cloud/how-to-connect-aws.md).
{% endtab %}

{% tab title="Azure" %}
Bluebricks connects to Azure through a registered application with federated credentials.

1. Register a new application in the Azure portal
2. Enter the **Application ID**, **Tenant ID**, and **Client Secret** in the Bluebricks wizard
3. Assign the **Contributor** role to the application on your subscription
4. Enter your **Subscription ID** and click **Connect**

For the full walkthrough, see [Connecting to Azure](/docs/getting-started/connect-your-cloud/how-to-connect-azure.md).
{% endtab %}
{% endtabs %}

Once connected, Bluebricks begins ingesting your cloud resources into the context layer. This usually takes a few minutes depending on the size of your environment.

{% hint style="info" %}
**Already completed the onboarding wizard?** To connect additional cloud providers or accounts, see [Connect your Cloud](/docs/getting-started/connect-your-cloud.md).
{% endhint %}

## 2. Connect your code

Next, connect your GitHub repositories so the agent can read your infrastructure code and propose changes through pull requests.

1. Click **Authorize** to start the GitHub OAuth flow
2. Install the Bluebricks GitHub App on your organization
3. Select the repositories that contain your infrastructure code

{% hint style="info" %}
**Don't use GitHub, or not ready to connect code yet?** You can skip this step. The agent can still discover and analyze your cloud resources without code access. You can connect code later from [Connect your Code](/docs/getting-started/connect-your-code.md).
{% endhint %}

The GitHub integration is read-only. Bluebricks does not modify your code directly; all changes are proposed through pull requests.

## 3. Talk to the agent

After connecting your cloud and code, Bluebricks redirects you to the agent. You are ready to ask your first question.

Try something like:

```
Show me all cloud resources that aren't managed by code
```

The agent queries the context layer, cross-references your cloud resources with your IaC repositories, and returns a breakdown of managed versus unmanaged resources across your accounts.

From here, you can follow up naturally:

* "Which of those are in production?"
* "Are any of them publicly accessible?"
* "Open a PR to bring the unmanaged S3 buckets under Terraform"

The agent handles follow-up questions in the same conversation, building on the context of what you have already discussed.

{% hint style="info" %}
The agent operates in read-only mode by default. When you ask it to make a change, it opens a pull request for you to review and approve before anything is applied.
{% endhint %}

## What's next?

Now that you are connected, explore what the agent can do for your team:

* **Review your security posture**: "Which security groups allow inbound traffic from 0.0.0.0/0?"
* **Find cost savings**: "Which EC2 instances have been idle for over 30 days?"
* **Make infrastructure changes**: "Scale the EKS cluster in staging to 5 nodes"
* **Set up orchestration**: create reusable blueprints and governed deployment workflows. See the [Orchestration Quick Start](/docs/orchestration/orchestration-quick-start.md) to deploy your first environment

Want to invite your team? See [Account Settings](/docs/organization-and-security/account-settings.md) to add members.


---

# 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/quick-start.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.