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:
- macOS or Linux on x64 or arm64 (glibc or musl); the installer is a POSIX
shscript - Git
- an SSH identity authorized to read the private Brix repository
The installer provisions Brix's private Node.js 24 toolchain and package manager under
BRIX_HOME (default ~/.brix). When a Node.js executable of the pinned version is already on
PATH, the installer copies only that executable into BRIX_HOME; otherwise it downloads its own.
You do not need to install Node, pnpm, Vite, or TypeScript separately for these commands. When an external runtime executes application code directly, Brix
requires Node.js 24.14.0 or newer for native #/ imports.
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:
curl -fsSL https://brix.strawberrylabs.dev/install.sh | sh
exec "$SHELL" -l
The bootstrap contains installer logic only; Brix itself is still fetched with your private Git SSH access. The installer runs only after the whole script has downloaded, so an interrupted download installs nothing.
When ~/.brix/bin is not already on your PATH, the installer appends it to your shell profiles
and prints each file it changed:
- zsh:
.zshrcand.zprofileinZDOTDIR(default~) - other shells:
~/.bashrc, plus the first existing file among~/.bash_profile,~/.bash_login, and~/.profile. When none exists it creates~/.profile, so an existing~/.profileis never shadowed by a new~/.bash_profile.
If a profile cannot be written, the installer prints the export PATH=... line to add yourself.
To install somewhere else, set BRIX_HOME for the installer, for example
curl -fsSL https://brix.strawberrylabs.dev/install.sh | BRIX_HOME=/opt/brix sh. The installed
brix command remembers that location, so later shells need only its bin directory on PATH.
Confirm that the launcher is available:
brix --version
Create a project
#With a fresh launcher, creation uses the stable channel by default:
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 agent skills. The project does not continue
following the channel automatically. Pass --version next only when deliberately testing a
prerelease, or --version v<version> for an exact release.
Before creating outside a project, the launcher refreshes the global CLI from its persisted
selection: stable unless you chose another with the installer or brix launcher update --version.
Use brix create app booking-web --version stable to choose stable explicitly; an explicit selector
is honored even when creation is launched from inside an existing standalone Brix project. An
explicit create --version activates that release as the global CLI but does not change the
persisted selection, so later creations follow it again. Inside a workspace, new members instead
inherit its exact version; omit a separate selector there.
brix create app . (or another project kind) populates an existing empty directory in place.
Use brix create app for the Hono, SSR, and Preact-islands application covered by these docs. Other
project shapes are:
brix create library booking-contracts # TypeScript library built with tsdown
brix create ui-library booking-ui # Preact component library with Panda styling
brix create workspace commerce # root for several applications and libraries
brix create react-app customer-portal # browser-only React application
brix create contentful-app booking-fields # Contentful App SDK interface
React applications are browser-only and do not have Hono routes, Preact islands, or the Node start
command. See application types and workspaces.
First checks
#Once the generated development server works, stop it and run:
brix doctor
brix check
brix test
brix build
doctor diagnoses project structure, managed configuration, and imports; check runs doctor plus
formatting, lint, and type checks. Run diagnosis from the project root. Outside a marked project or
workspace, doctor reports that the directory is not a Brix project; use brix init only if you
intend to adopt it.
Keep the generated package.json lifecycle scripts as direct Brix commands, such as
"check": "brix check". Doctor rejects command mentions hidden inside unrelated executables or
shell control flow; ordinary arguments and simple environment, env, or exec prefixes are
supported. See CLI for the delegation grammar.
Continue with project structure and pages. See deployment when you are ready to serve production output.
Work with an existing checkout
#After cloning a Brix project, restore the exact declared release and dependencies:
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.
When that exact release is already cached under BRIX_HOME, preparing it needs no network access,
so a new clone or Git worktree can run brix install --offline with a populated package cache.
Dependency installation and upgrades also use SSH for the Brix repository, even when the package manager normalizes its URL to HTTPS. Brix applies its repository-scoped Git setting only to child processes; your SSH identity must already have repository access.
For older manifests, brix install migrates the installation root's top-level allowBuilds map to
allowScripts. Existing allowScripts entries take precedence; nested pnpm.allowBuilds and YAML
settings remain unchanged. Review and commit that migration before lockfile-exact brix ci, which
does not migrate the manifest. The bootstrap uses the selected release's pinned package manager,
so it does not rewrite an older release merely to use the newest installer's tooling.
To adopt a compatible existing project, inspect the plan before changing files:
cd existing-project
brix init --dry-run
brix init
init refuses incompatible files rather than overwriting them. An existing tsconfig.json is read
the way TypeScript reads it, so comments and trailing commas are fine; init adds the Brix baseline
to extends in place and keeps the rest of the file, including its comments. Invalid JSON is
reported with its line and column. Outside a project, init first refreshes the global CLI like
create; init --dry-run instead runs the refreshed CLI without activating it, so a preview never
changes the global CLI.
Upgrade deliberately
#Review the stable upgrade plan first:
brix upgrade --dry-run
brix upgrade
Dry runs are allowed with a dirty worktree or outside Git. The real project or workspace upgrade
requires a committed, clean Git working tree with no untracked files (ignored files are allowed),
and checks that before updating the global CLI. It writes the resolved exact release, installs and
migrates dependencies, configuration, and skills transactionally, and rolls back those managed
changes if installation or migration fails. It does not run lint, tests, builds, or brix verify.
After success, review the migration diff, apply required code migrations, then run brix verify;
that separate verification cannot undo the upgrade. Same-version commands reconcile managed state
and describe the operation as a reconcile. A stable project follows the stable channel by default;
select --version next explicitly to evaluate a prerelease.
Manage the global CLI
#The global CLI runs create, init, and commands outside projects; project commands always use
the project's pinned release. brix upgrade and create --version activate their selected release
globally for that operation only. To change what the global CLI follows, select it explicitly:
brix launcher update # refresh the persisted selection
brix launcher update --version next # follow next releases from now on
brix launcher update --version v2.8.0 # freeze at an exact release
While frozen at an exact release, brix launcher update says so; run
brix launcher update --version stable to follow the stable channel again.
brix launcher rollback restores the previous global CLI. Afterwards, create and init stop
refreshing automatically, so the rollback is not undone by the next creation. Run
brix launcher update, brix upgrade, or pass an explicit create --version to resume.
Each release used by the launcher or a project bootstrap is cached under BRIX_HOME/versions.
After each installation, Brix removes cached releases other than the current and previous global
versions, any release used within the last day, and the three most recently used others. It also
removes leftovers from interrupted installations. Pruning is best effort: an entry Brix cannot
delete, such as one created by a sudo run, is left in place and never fails the installation.
Recover from setup failures
#Transactional setup normalizes stable symlinked parents, but rejects symlink-managed roots and
unsupported nested links before mutation. Ordinary package
links inside node_modules and generated skill links remain supported. Do not edit managed paths
concurrently with setup or rollback.
Interrupting a transactional command (init, create, upgrade, deps add|remove|update,
workspace link/adopt/integrate, or storybook init) with Ctrl-C (SIGINT) or SIGTERM does not
abort its rollback. Brix lets the running tool stop, restores the snapshotted files and installed
state, reports Interrupted by SIGINT; restored the previous project state., and then exits by the
same signal. Pressing Ctrl-C again during rollback is ignored. SIGKILL cannot be deferred and can
leave partial state; use it only as a last resort.
Transactions copy manifests, lockfiles, configuration, and sources, but not node_modules. When a
failed or previewed step changed installed dependencies, rollback first restores the lockfile and
then reinstalls it with --frozen-lockfile, normally from the local package cache. If that
reinstall fails, Brix reports an incomplete rollback; the restored lockfile is kept, so run
brix install once the cause (for example an unreachable registry) is fixed.
Stopping an interrupted install is best effort. On POSIX, Brix signals the package engine's process group and force-kills members that outlive it after a short grace period; detached processes in other groups are not covered. Windows signals only the direct child. Stop any remaining install processes before recovering or retrying.
- If the shell cannot find
brix, reload it as shown above. Check that a profile the installer reported as updated is one your shell reads, or add theexport PATH=...line it printed for a profile it could not update, before reinstalling. - If a fetch is denied, verify that the same SSH identity used by this shell can read the private repository. Installing another package manager will not grant access.
- If a checked-out project reports a version mismatch, run
brix installfrom its installation root; do not edit the framework pin to match whichever CLI happens to be installed globally. - If
initrefuses an executable config, preserve the existing file and reconcile its supported options with the Brix helper before retrying. Do not delete custom configuration blindly.
Use brix --verbose install when the normal failure summary lacks enough context. Keep private
logs private until you have checked them for credentials.