Creating Environments

Create environments from the Bluebricks app or CLI to deploy blueprints into collections

Overview

An environment binds a blueprint to a collection and triggers the first run, provisioning your infrastructure. You can create environments directly from the Bluebricks app, the CLI, the API, manifest files, or webhooks. This guide focuses on the Bluebricks app and CLI workflows.

For conceptual background on environments and how they work, see Environments.

Prerequisites

All methods require a collection with at least one connected cloud account. See Creating Collections. Additional prerequisites depend on how you create the environment and are listed in each section below.

How to create an environment in the Bluebricks app

The Bluebricks app provides a guided wizard for creating environments.

From the Environments page, click create environment to get started.

You choose one of two paths:

• From code: connect a Git source or use an existing blueprint

• From cloud: import unmanaged cloud resources into a managed environment via the Cloud Import Agent

When to use "From code"

Choose this when you are deploying new or existing infrastructure from IaC source code. You either point to a Git repository containing your Terraform, OpenTofu, or other IaC configuration, or select a blueprint your team has already published.

This is the standard path for writing infrastructure from scratch or bringing existing code under Bluebricks management. Jump to the instructions

When to use "From cloud"

Choose this when you have existing cloud resources that were created outside of Bluebricks and want to bring them under management. The Cloud Import Agent scans the cloud account associated with your collection, lets you select resources, and generates the IaC code for you.

Choose this path when you have infrastructure already running that you want to codify and manage on Bluebricks going forward. Jump to the instructions

How to create from code

Choose From code when you already have IaC source code in a Git repository or a published blueprint ready to deploy.

After selecting a collection and naming the environment, you pick one of two tabs:

• Connect source: Use this tab to create a new environment directly from a Git repository.

• Use existing blueprint: Use this tab when you already have a published blueprint and want to deploy it into a collection.

Connect source

Prerequisites: a public or private Git repository with IaC code.

If you're using a private Git repository, you need the GitHub integration.

1

Select a collection and name the environment

Choose the target collection and enter a descriptive slug (e.g., git_ops_prod).

2

Set source code

Select the IaC technology (OpenTofu, Terraform, etc.), provide the Git remote URL, branch, and optionally a subdirectory path.

3

Define a blueprint

Give the blueprint a name and optional description. This blueprint wraps your source code so you can reuse it across your organization. See Blueprints for more on how blueprints work.

4

Create the environment

Click Create to generate the blueprint and environment. Bluebricks triggers the first run automatically.

Use existing blueprint

Prerequisites: a published blueprint. See Creating Blueprints.

1

Select a collection and name the environment

Choose the target collection and enter a descriptive slug.

2

Select a blueprint

Choose the blueprint you want to deploy from the dropdown.

3

Create the environment

Click Create to create the environment and trigger the first run.

How to create from cloud

Choose From cloud to import and codify existing unmanaged cloud resources into a managed environment.

1

Select a collection

Choose the collection you want to import resources from.

2

Go to the Cloud Graph

Click Go to graph to open the resource explorer, where you can select cloud resources to import and codify. See Cloud Import Agent for more details.

How to create an environment via the CLI

Use the bricks install command to create an environment from the terminal.

Prerequisites: Bricks CLI installed and authenticated. See Bricks CLI.

Basic example

bricks install @bluebricks/postgres --collection=production --props-file=path/to/props.json

Plan-only (preview changes without applying)

bricks install @bluebricks/postgres --collection=production --props-file=path/to/props.json --plan-only

Key flags

Flag	Description
-c, --collection	Collection slug as the deployment target
--deployment	Deployment slug
--set-slug	Set a custom environment slug
-p, --props	JSON string containing blueprint properties
--props-file	Path to a JSON file containing blueprint properties
-f, --file	Path to a YAML manifest file (bricks/v1 schema) for non-interactive use
--plan-only	Create a plan without applying
-y, --yes	Skip confirmation and deploy directly

For the full command reference, see bricks install.

Other ways to create environments

• API: use the POST /api/v1/env/create endpoint. See the Envs API reference.

• Manifest file (CI/CD): define environments declaratively using a manifest file. See Environment Manifest File Format and Managing Configuration on Git.

• Webhooks: trigger environment creation from external systems. See Webhooks.

What happens after creation

When you create an environment, Bluebricks automatically triggers the first run in plan phase. The unified plan shows all proposed infrastructure changes across every package in the blueprint.

Review the plan, then approve to apply the changes and provision your infrastructure. For full details on the run lifecycle, see Runs.