Quick Start

Welcome to the Bluebricks 👋 Use this guide to get a feel for the platform and get your first environment up and running.

This guide walks you through the core Bluebricks workflow end to end. By the time you finish, you will have a live environment and a reusable blueprint that defines it.

Before you start

We recommend reading What is Bluebricks to understand the core concepts before getting started.

You will also need:

• A Bluebricks account with admin-level permissions (sign in at app.bluebricks.co)

• Access to at least one cloud provider (AWS, GCP, or Azure)

Let's get started!

1. Create a collection and connect a cloud provider

A collection is the connecting layer between Bluebricks and your cloud provider. It represents a single cloud account, subscription or project that Bluebricks can discover, orchestrate, and manage.

You use collections to define where Bluebricks operates.

To create a collection:

1

Create a collection

1. Go to the Collections page in the Bluebricks app

2. Click Create collection

3. Enter a name (for example, dev-quickstart)

2

Connect your cloud provider

Continuing from the create collection dialog:

1. Select your cloud provider: AWS, GCP, Azure, or Self-hosted

2. In Account Number / ID dropdown, click Create new

3. Follow the dedicated setup steps providing Bluebricks with the necessary permissions

   1. For provider-specific instructions, see Connect your Cloud

4. Click Connect & Create

2. Create a blueprint

A blueprint defines what environment should be deployed and how its components work together. It is a reusable, versioned definition that composes packages (IaC component) into a complete environment.

You use blueprints to define what gets deployed.

1

Create a blueprint

1. Go to the Packages page and click Create Blueprint

2. Enter a descriptive name for the infrastructure pattern this Blueprint defines. For example: application-service, ecommerce-service

   1. A good blueprint name is:

      • Descriptive - reflects the purpose or workload

      • Reusable - not tied to a specific account or region

      • Concise - short and easy to scan

2

Create artifact

There are two ways to create an artifact depending on where your code is stored.

If you’ve connected GitHub (or are using a public repo), you can create artifacts directly in the Bluebricks app. If you’re working from a private Github repo or an alternative VCS, artifacts should be published using the CLI.

Choose how you want to create and publish your artifact:

Create an artifact directly from the Bluebricks app

Use this option if you’ve enabled the GitHub integration or are using a public GitHub repository and want your repo to serve as the artifact’s source of truth. Changes to the code will automatically trigger an update process.

To add a package:

1. In the packages field, click + Add then click New Package

2. Choose the repository and directory that contains your IaC code (for example, a Terraform root module)

3. Fill in the artifact details: name, description, and IaC type

4. Click Create package

Create an artifact with the bricks CLI

Use this option if your code is in a private repository without the GitHub integration or hosted in another VCS. Artifact updates must be published via your CI pipeline or manually using the CLI.

To add the package:

1. Open your code’s root directory Use the folder you’d normally run directly (e.g. terraform init/apply or helm install).

2. Publish with the CLI Run from that directory:

   bricks bprint publish

   This generates bricks.json and publishes the artifact to the Bluebricks catalog.

3. Verify in Bluebricks Go to the Artifacts page in the Bluebricks app to view your newly published artifact and continue to the next step.

Enable the GitHub integration (optional)

If you are using private repos, enabling the GitHub integration allows Bluebricks to pull IaC packages (like Terraform or Helm) directly from your repositories. This enables you to build and deploy blueprints without uploading code manually.

To integrate GitHub with Bluebricks:

1. Go to integrations in the account settings:

   1. Click your profile picture > Account Settings > Integrations

2. Click GitHub then click + Add new

3. Select the repository and install Bluebricks

If you need further help, check out the GitHub integration article.

3

Configure inputs

Review the inputs that your artifact exposes. For each one, decide whether it should be:

• Required: the deployer must provide a value at run time

• Default: pre-filled but overridable by the deployer

• Allowed Values: list of permitted values. Deployers must choose from this list.

When you are happy with the configuration, save and publish the blueprint. For a deeper walkthrough, see Creating Blueprints.

If you want to dictate the value without the deployer being able to later modify it - change it on packages level.

3. Create and deploy an environment

An environment is an instance of a blueprint within the collection. It tracks the full lifecycle of your infrastructure: planning, applying, and tearing down resources.

You use environments to define how it runs.

To deploy an environment:

1. Click the Deploy on the top right to be redirected to the run deployment wizard

2. In Target collection, select the Collection you created in step 1

3. In Environment name, click Create new environment and name it

4. In blueprint, select the blueprint you just published

5. Fill in any required properties that you defined while creating the artifact

6. Click the blue Deploy button on the bottom right

For more details, see Creating Environments.

4. Review the plan

After deploying, the environment generates a unified plan showing every change across all packages in the blueprint as well as the status of the run.

Run failed?

If your run shows a Failed status, the review logs will open automatically to help you understand what went wrong.

The logs highlight the exact step or package that caused the failure, making it easier to troubleshoot.

Once the run completes (it can take a few minutes), your resources are live in the target cloud account. 🎉

Need additional help?

Check out our Help Center at help.bluebricks.co for guides, FAQs, and support resources.

What's next?

Now that you have a running environment, explore these areas to get more out of Bluebricks:

Properties

Configure default properties

Policies

Add approval flows and cost controls

Secrets

Configure defaults and sensitive values

bricks CLI

Manage Collections, Blueprints, and Environments from the command line

Drift detection

Automatically detect when infrastructure drifts from the desired state

MCP

Let AI agents interact with Bluebricks through the Model Context Protocol