Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
@carbon/dev
Developer CLI (crbn command) — worktree management, Docker Compose stacks, migrations, portless dev URLs, and app lifecycle.
Always
- Use the
crbnCLI for stack operations —crbn upboots Docker + apps,crbn downtears down,crbn newcreates worktrees,crbn statusshows state - Bash router handles
checkout— thebin/crbnshell script routes lightweight commands; heavy commands delegate totsx packages/dev/src/main.ts(citty) - Respect the slot system —
resolveSlot()/getSlot()manage port allocation per worktree to avoid conflicts - Guard platform compatibility —
bin/crbnvalidates OS (POSIX only: Linux, macOS, WSL, Git Bash) and Node 24.22.1+
Ask First
- Changing Docker Compose service definitions or port mappings
- Modifying the portless proxy setup (
services/portless.ts) - Adding new
crbnsubcommands (register insrc/main.tssubCommands)
Never
- Run
crbn upwithout Docker running — it callsensureDockerRunning()first - Hardcode ports — use the slot/worktree resolution system
- Skip migrations on stack boot unless explicitly passing
--no-migrate
Validation Commands
pnpm --filter @carbon/dev test # vitest
pnpm --filter @carbon/dev typecheck # tsc --noEmit
pnpm --filter @carbon/dev smoke # real containers: slots, fresh migrate, up, status, purge (~40 s, needs Docker; run from a worktree with no stack)
Key Patterns
- Commands:
up,down(--purgereleases the slot),new,init,remove,prune(destroys stacks whose worktree directory is gone or that have no slot — the cleanup for worktrees deleted withoutcrbn remove;--alldestroys every stack on the machine and keeps worktrees and live slots;--treealso runsgit worktree prune, and with--allremoves this repo's linked worktrees — never the main checkout, the current one, or one with uncommitted changes or a detached HEAD; branches are kept),list,status,reset,migrate,restore,copy(env sync),reload(crbn reload <service...>→docker compose up -d --force-recreatea subset, applying compose/.env.localedits without restarting the app dev servers) - Restore (
commands/restore.ts):crbn restore <file>wrapsscripts/restore-database.sh(the SQL is deliberately NOT ported) and adds worktree/PORT_DBresolution, a confirmation gate, and the trailingapplyMigrations+db:types. The script truncates the localsupabase_migrationsledger before restoring so the dump's own ledger lands — the ledger must travel WITH the schema, else the dump's older schema pairs with the local newer ledger and the trailing migrate step silently no-ops (leaving weeks of migrations missing while the ledger claims them applied). It deliberately does NOT boot a partial stack the waycrbn migratedoes — a restore rewritesauth/storage, whose schemas GoTrue and Storage build via their own migrations, so it requires a fully booted stack (serviceSchemasReadyprobes for GoTrue'sauth.users.email_confirmed_at,storage.objects/storage.bucketsAND Realtime'srealtime.messages— the restore script'sto_regclassguards mean a missing Storage schema would otherwise let the restore finish with no buckets seeded) and refuses otherwise — the backup carries the SOURCE schema, which is usually behind the branch.--scrub-emailsdefaults ON here, inverting the script's opt-in default, so a restore cannot drop real customer addresses into a local DB unless asked. By default the script truncatesstorage.objects(kept rows would point at files that live only in the source environment's backend, so downloads 404); pass--keep-storage-objectsto retain them and the dump's buckets when you need realistic storage metadata, e.g. profiling storage RLS. The script fits the dump to this stack's own service schemas before psql reads it. It trims each non-publicCOPYto the local columns, drops a block whose table does not exist locally, and skips the backup's auth, storage and realtime admin-owned functions. ACOPYthat fails to parse makes psql read its rows as SQL, and that once swallowed the whole post-data section. Afterwards the script verifies everypublicindex, constraint, trigger and policy against the dump by name, and the ledger row count. It re-adds a foreign key that cannot be validated (a backup is not one snapshot) asNOT VALID, and it exits 1 on any shortfall or missing storage buckets. Socrbn restorenever migrates a schema that did not land. - Stack boot (
commands/up.ts): Docker Compose → wait Postgres → wait service schemas → migrations → regen types → spawn apps → portless aliases - Migrations need three services, not just Postgres: they write into
storage.buckets, GoTrue'sauthcolumns andrealtime.messages, which Storage, GoTrue and Realtime build on first boot.waitForServiceSchemasgates every migrate on a fresh volume; standalonecrbn migratebootspostgres+gotrue+storage+realtimefor the same reason. A from-zero migrate takes about 5 s once they are up, so there is nothing to gain from caching a migrated volume. - Stack size (
StackSize/profileArgsinservices/compose.ts):crbn upstarts the eight services the apps need (Inbucket included, for login emails).--fulladds Studio, Postgres-Meta, the edge runtime and imgproxy (compose profilefull). Nothing in the apps calls the first three, and they were ~40% of a stack's memory; imgproxy only converts HEIC and images the wasm pipeline refuses, and a transform attempted without it logsimageTransformErrorMessage(@carbon/files), which says to runcrbn reload imgproxy.--minimalalso drops Inbucket (profilemail). Picking Studio in thecrbn upapp picker (orstudioinCARBON_DEV_APPS) enables profilestudioinstead, which holds only Studio and Postgres-Meta; it is a compose service, so a pick of Studio alone is still services-only mode.crbn reload studiostarts Studio on a running stack.generate:swaggerreads PostgREST through Kong with the anon key (byte-identical to what Studio served), so it works at every size. - Provision (
commands/init.ts):crbn initprovisions an already-created worktree (canonical slug + env sync + skills) to match acrbn checkout; shared bynew, the bashcheckoutpost-create hook, and Conductor'ssetup(.conductor/settings.toml). It does NOT boot the stack —crbn upstill mints ports/.env.local. - Worktree (
worktree.ts):resolveSlug(),canonicalSlug()(branch-derived<repoBase>-<branch>),getWorktreeRoot(),projectName(),ensureSlugAvailable() - Services:
compose.ts(Docker),migrations.ts(Postgres/Supabase),portless.ts(.devURLs),apps.ts(dev servers) - Aux spawners (
services/apps.ts):spawnAssembler(cargo;crbn upfirst refuses the assembler with an install hint whileassemblerMissingPrerequisitenames Rust, FCL or the OCCT build as missing, and builds into the shared~/.cache/carbon-cargo-target,assemblerCargoTargetDir) andspawnEmailPreview(@carbon/documentsemail:previewsonPORT_EMAIL— the react-email server oversrc/email/previews, one fixture per email) — opt-in picker apps with their own spawners, not react-router dev servers - Vite helpers (
vite.js, exported as@carbon/dev/vite, typed byvite.d.ts):carbon({ command, mode, locales, clientOnly, splitServer, precompress })is each app's one plugin call, listed aftertailwindcss()andreactRouter()(which stay in the app). It always adds stack activity and Lingui's macro transform (withlinguiWithoutIdQuery, which works around Lingui 6.9.0 parsing React Router's?query-suffixed route ids as plain JS), and on request react-aria's locale trimming (locales),clientOnlyAliasstubs (clientOnly),splitServerByPackage(splitServer: one server chunk per package, so Vercel's file trace stays fast; only modules loaded at startup are grouped) andprecompressedAssets(precompress). Packages are imported only when their plugin runs; hooks use native filters.applyDotenvToProcessEnvstays a separate call. Lingui,@lingui/confand the react-aria plugin are peer dependencies the apps provide - Spinners come from
ui.ts, not@clack/prompts:tasks,spinnerandprogressthere print one line per step when stdout is not a terminal (an agent, a pipe, a log file) instead of every animation frame. Importing them from clack directly brings the frame noise back. - No command allow-list in
bin/crbn: the bash router runs from the main checkout while the TypeScript CLI runs from the current worktree, so the router passes anything it doesn't own (checkout, help, version) straight through. Register a subcommand insrc/main.tsonly. - Prompts need a terminal — say so: a clack prompt with no TTY ends the process without a word. Every prompt calls
requireTerminal(what, instead)(prompts.ts) first, which throws a one-line error naming the non-interactive route:CARBON_DEV_YES=1for the confirms,crbn remove <branch-or-path...>,crbn new --yes <branch>. --jsononstatusandlistprints machine-readable output (ports, redis db, containers; never the JWT secret).- Read-only compose calls pass
--env-file(envFileArgs): compose interpolates the whole file beforeps/logs, and it has values with no default, so without.env.localthose calls fail and report an empty stack. restart: on-failureon every compose service: a crash restarts the container, a Docker daemon start does not. A stack only comes up throughcrbn up.- The slot registry is locked (
lockRegistryinworktree.ts): every change to~/.carbon/dev-ports.jsonis read → decide → write under amkdirlock, written through a temp file + rename. Conductor boots workspaces concurrently; without the lock eight simultaneouscrbn upleft one slot in the file. Any new writer must take the lock. - Compose reads throw (
composeReadinservices/compose.ts):listContainersandlistComposeServicesraise compose's own error instead of returning an empty list, which used to pass for "no stack". - Hibernation (
services/hibernate.ts+stackActivity()invite.js), two stages whilecrbn upruns ERP/MES:- Stack — the dev servers touch
~/.carbon/stacks/<slug>/activityon each request (/api/inngestexcluded: Inngest polls it every 5 s). AfterCRBN_IDLE_MINUTES(default 30) without one,crbn upwrites anasleepmarker holding its pid and runsdocker compose stop. The next request is held by the plugin whilecrbn uprunsbootStackand waits for Postgres and the API — about 8 s. - Dev servers — they hold more than the containers (roughly 1 GB each). After
CRBN_APPS_IDLE_MINUTES(default 120)crbn upaborts them (spawnApps'signal) and listens on their ports itself (startWaker). A request there cannot be handed over — the dev server needs that port — so a browser gets a page that polls and reloads, anything else a 503 withx-crbn-waking. Inngest polls and WebSocket upgrades (an open tab's Vite client probing for its server) do not wake it. That wake is about 40 s: the dev servers boot from cold. - Off for
--no-apps,--run,--borrow(the owningcrbn updoes it) and--no-hibernate. Traffic that never reaches ERP/MES (psql, scripts on the API) does not count;crbn migrateandcrbn restorewake a sleeping stack themselves (wakeIfAsleep).crbn listandcrbn statusshow a hibernated stack.
- Stack — the dev servers touch
crbn prunealso clears stale portless routes (findStaleAliases): static aliases crbn registered whose port no live slot owns.portless pruneonly reaps routes that have a process.- Env:
env.ts—renderEnv(),writeEnv(),syncAppPortlessConfigs(). URLs derived from the stack's ERP host (ERP_URL,VERCEL_URL,INNGEST_SERVE_HOST,ONSHAPE_V2_OAUTH_REDIRECT_URL) come from oneerpUrl; a key a developer must keep fixed (a tunnel, a registered redirect URI) is pinned in.envwith#force. Keys copied from.env(with an optional default) are listed once inFROM_DOT_ENV --runflag: scopes stack lifetime to a command (for headless/CI builds);--volumescleans up Docker volumes on teardown
Cross-References
packages/harness/— usescrbn up --runfor headless agent buildspackages/database/— migrations applied duringcrbn updocker/— Compose files consumed by the stack boot