Local development
Run the full Carbon stack locally with the crbn CLI, in isolated per-worktree environments.
Carbon is a pnpm and Turborepo monorepo containing the ERP and MES applications and shared packages. The crbn CLI in packages/dev manages local environments. Each Git worktree receives an isolated Compose stack, ports, Redis database, and JWT credentials, so multiple branches can run concurrently.
Setup
Bring up the stack
From a worktree, start the Compose services and the ERP and MES development servers:
crbn upThis generates .env.local with worktree-specific ports, local Supabase keys, REDIS_URL, Inngest development settings, and DEV_BYPASS_EMAIL.
Reach the apps
Open the applications at their portless .dev URLs or localhost:<port>.
DEV_BYPASS_EMAIL is local-only. It signs you in as that email with no magic link. Never set it in a deployed environment.
Stack commands
| Command | What it does |
|---|---|
crbn up | Boot the compose stack and apps. |
crbn up --no-portless | Localhost mode: fixed ports (API 54321, ERP 3000, MES 3001). |
crbn up --no-apps | Services only: Postgres, Kong, Supabase, Inngest, mail. |
crbn up --no-migrate | Skip database migrations on boot. |
crbn up --no-regen | Skip type and Swagger regeneration. |
crbn up --borrow | Reuse another worktree's already-running containers. |
crbn up --pull | Force docker compose pull even if images exist locally. |
crbn down | Stop the stack (volumes preserved). |
crbn reset | Wipe volumes and flush the Redis db, then boot again. |
crbn migrate | Apply database migrations against the running stack. |
crbn status | Show port assignments and container health. |
pnpm dev is shorthand for crbn up --no-portless: localhost mode on fixed ports.
Worktrees
Each branch gets an isolated worktree and stack, so several can run side by side.
| Command | What it does |
|---|---|
crbn checkout <branch> | Switch into a branch's worktree, creating it if missing (auto-fetches from origin). |
crbn checkout -b <branch> | Create a new branch and worktree from --base (default HEAD). |
crbn checkout <pr-number> | Fetch a PR's head into a pr-<num> branch and worktree. |
crbn checkout main | Return to the main checkout (never a separate worktree). |
crbn new [branch] | Create a worktree interactively. |
crbn list | List all worktrees with their stack status. |
crbn remove | Multi-select worktrees to tear down; add --prune to delete the branch too. |
Portless vs localhost
By default, crbn up uses portless to assign each application a stable TLS .dev URL, such as erp.<branch>.dev. Pass --no-portless or set CARBON_PORTLESS=0 to use fixed localhost ports:
| Service | Port |
|---|---|
| Supabase API (Kong) | 54321 |
| ERP | 3000 |
| MES | 3001 |
Sync files from main
A new worktree does not include Git-ignored local files. Copy them from the main checkout:
| Command | What it does |
|---|---|
crbn copy <file…> | Copy specific file(s) from the main checkout into this worktree. |
crbn env sync | Copy the files listed in package.json under crbn.copy. |
Configuration
Your local settings live in the generated .env.local. See Environment variables for the full configuration surface, and Self-hosting to run Carbon on your own infrastructure.