Create a Bruin Project

Why this step matters

Before an AI agent can analyze your data, it needs somewhere to store the knowledge it will work with — table schemas, column descriptions, quality checks, and domain context. A Bruin project is that workspace. It's a plain folder on your machine with a small config file (.bruin.yml) and one or more asset directories that describe your data.

Think of it like a README for your database, but machine-readable. Without this structure, the AI agent would be flying blind — guessing table names, inventing column meanings, and writing queries that may not even run. The project gives it ground truth.

If you already have a Bruin project, skip ahead to Step 2: Connect Your Data.

What you'll do

Create an empty Bruin project using the CLI. This gives you the folder structure and config file that every other step builds on.

Video walkthrough

If you prefer video, this core concept walkthrough covers project initialization end-to-end:

Instructions

Bruin projects must live inside a git repository — that's how Bruin tracks changes and ensures your data context is version-controlled. If your current folder is already a git repo, bruin init will create the project right inside it. If it's not, Bruin will automatically run git init for you, so you don't need to do it manually.

Open your terminal and run:

bruin init empty my-project
cd my-project

This creates a folder called my-project with:

my-project/
├── .bruin.yml            # project config — connections, environments
└── my-analyst/
    ├── pipeline.yml      # folder config — name, schedule, defaults
    └── assets/           # where your table definitions will live

bruin init names the inner folder after the project by default. You can rename it to anything — we use my-analyst here to keep things clear.

If the current directory was not a git repo, Bruin creates a bruin/ parent folder, initializes git there, and places your project inside it. Either way, the structure inside the project is the same.

You can name the project anything — my-project is just a convention for this tutorial. Pick whatever makes sense for your team.

What just happened

You now have a local Bruin project with a .bruin.yml config file ready to accept database connections and an assets folder waiting for table definitions. The project is version-controllable from day one, so your entire data context can live alongside your code.