> [Agent navigation index](/llms.txt)

# Installation

Install the Brix launcher and create a project whose framework and tools are pinned together.

## Prerequisites

Brix 2 is stable and distributed from a private Git repository. Before installing, you need:

- Git
- an SSH identity authorized to read the private Brix repository
- a shell supported by the bootstrap installer

CI should use a dedicated read-only deploy key rather than a developer's key.

## Install the launcher

Run the public bootstrap, then reload your shell:

```sh
curl -fsSL https://brix.rellim.dev/install.sh | sh
exec "$SHELL" -l

```

The bootstrap contains installer logic only. Resolution of Brix itself still requires your private Git SSH access.

Confirm that the launcher is available:

```sh
brix --version

```

## Create a project

Creation uses the stable channel by default:

```sh
brix create app booking-web
cd booking-web
brix dev

```

`create` resolves `stable` to an immutable version tag, records that exact Brix dependency, installs the template dependencies, and exposes version-matched skills. The project does not continue following the channel automatically. Pass `--version next` only when deliberately testing a prerelease.

Use `brix create app` for the Hono, SSR, and Preact-islands application covered by these docs. Other supported project shapes include:

```sh
brix create library booking-contracts
brix create workspace commerce
brix create react-app customer-portal

```

React applications are browser-only and do not have Hono routes, Preact islands, or the Node `start` command.

## Work with an existing checkout

After cloning a Brix project, restore the exact declared release and dependencies:

```sh
brix install
brix doctor

```

If a pulled commit changes the declared Brix version, `brix install` adopts that exact version. Other commands reject a mismatch instead of silently using another framework release.

To adopt a compatible existing project, inspect the plan before changing files:

```sh
cd existing-project
brix init --dry-run
brix init

```

`init` refuses incompatible files rather than overwriting them.

## Upgrade deliberately

Review the stable upgrade plan first:

```sh
brix upgrade --dry-run
brix upgrade

```

The real upgrade writes the resolved exact release, installs it, and verifies the project transactionally. A stable project follows the stable channel by default; select `--version next` explicitly to evaluate a prerelease.

## First checks

Once the generated development server works, run:

```sh
brix check
brix test
brix build

```

Continue with [project structure](/docs/project-structure) and [pages](/docs/pages). See [deployment](/docs/deployment) for the supported production build and Node start workflow.