crbnos/carbon: Carbon is an open source ERP, MES and QMS for manufacturing. Perfect for complex assembly, contract manufacturing, high volume, and configure to order manufacturing.

Carbon

The open core for manufacturing.
ERP · MES · QMS — API-first, extensible, yours.

Website · Documentation · Discord · Roadmap

!ERP Screenshot

!MES Screenshot

Contents

• Why Carbon
• Features
• Architecture
• Tech Stack
• Monorepo
• Getting Started
• Local Dev CLI (crbn)
• Environment Variables
• Logging In
• Commands
• API
• Migration Notes

Why Carbon

We built Carbon after years of building end-to-end manufacturing systems with off-the-shelf solutions. We realized that:

• Modern, API-first tooling didn't exist
• Vendor lock-in bordered on extortion
• There is no "perfect ERP" because each company is unique

Features

| | | | ------------------ | --------------------------------------------------- | | ERP | Sales, purchasing, inventory, items, accounting | | MES | Shop floor execution and job operations | | QMS | Inspections, non-conformances, CAPAs | | MRP | Material requirements planning | | Traceability | Full lot and serial tracking | | Nested BoM | Multi-level bills of material | | Configurator | Product configuration | | Capacity Planning | Scheduling against real resource capacity | | Custom Fields | Extend any record | | API & Webhooks | Build your own apps on top of Carbon | | MCP Client/Server | AI-native integration surface | | Accounting | GL, journals, and third-party sync |

See the full roadmap for what's next (up next: Simulation).

Technical highlights

• Unified auth and permissions across apps
• Full-stack type safety (Database → UI)
• Realtime database subscriptions
• Attribute-based access control (ABAC)
• Role-based access control (Customer, Supplier, Employee)
• Row-level security (RLS)
• Composable user groups
• Dependency graph for operations
• Third-party integrations

Architecture

Carbon is designed to make it easy for you to extend the platform by building your own apps through our API. We provide some examples to get you started in the examples folder.

!Carbon Functionality

!Carbon Architecture

Tech Stack

| Layer | Technology | | ---------- | --------------------------------------------------------------------- | | Framework | React Router | | Language | TypeScript | | Styling | Tailwind | | Behavior | Radix UI | | Database | Supabase (Postgres + RLS) | | Auth | Supabase | | Cache | Redis | | Jobs | Inngest | | Email | SMTP (Nodemailer) | | i18n | Lingui | | Hosting | Vercel | | Billing | Stripe | | Geometry | Rust (FCL collision + OpenCASCADE CAD) |

Monorepo

The monorepo follows the Turborepo convention of grouping packages into two folders:

carbon
├── apps         # applications
└── packages     # shared code

/apps

| App | Description | How to run | | ----------- | -------------------------------------------------------------- | --------------------------------------------------- | | erp | ERP application | pnpm dev (boots stack + ERP via crbn up picker) | | mes | MES — shop floor | pnpm dev (select MES in picker, or both) | | academy | Training | pnpm dev:academy | | starter | Example app built on the API | pnpm dev:starter | | assembler | Geometry service (Rust): STEP → GLB + assembly motion planning | spawned by crbn up (needs a release binary — see Optional: assembler) |

pnpm dev runs the per-worktree dev CLI (crbn up). ERP and MES are first-class — the CLI boots the docker stack, applies migrations, regenerates types/swagger, and spawns the selected apps behind portless. The assembler geometry service is spawned too when its release binary is present. Academy and starter are standalone Turborepo entries.

/packages

| Package | Description | | ------------------- | --------------------------------------------------------------------------- | | @carbon/database | Database schema, migrations and types | | @carbon/documents | Transactional PDFs and email templates | | @carbon/ee | Integration definitions and configurations | | @carbon/config | Shared configuration (vitest, tsconfig, tailwind) across apps and packages | | @carbon/jobs | Background jobs and workers | | @carbon/logger | Shared logger used across apps | | @carbon/react | Shared web-based UI components | | @carbon/kv | Redis cache client | | @carbon/lib | Third-party client libraries (slack, resend) | | @carbon/stripe | Stripe integration | | @carbon/utils | Shared utility functions used across apps and packages |

Getting Started

Prerequisites

• Docker — the monorepo uses Docker for local development
• Node.js v22 (via nvm)
• pnpm (via Corepack — see below; never npm)

| Service | Purpose | | ---------------------------------------------------- | -------------------------- | | Posthog | Product analytics platform | | Stripe | Payments service | | An SMTP provider (e.g. Resend) | Email service |

Posthog has a free tier which should be plenty to support local development. If you're self hosting and you don't want to use Posthog, it's pretty easy to remove the analytics.

Clone

Clone the repo into a public GitHub repository (or fork https://github.com/crbnos/carbon/fork). If you want to make the repo private, you should acquire a commercial license to comply with the AGPL license.

git clone https://github.com/crbnos/carbon.git
cd carbon

Install

This repo uses pnpm as its package manager. Enable Corepack so the correct pnpm version (pinned via packageManager in package.json) is used automatically:

corepack enable    # one-time: activates pnpm shim from packageManager field
nvm use            # use node v22
pnpm install       # install dependencies

The dev stack (Postgres, GoTrue, Kong, Storage, Inngest, Inbucket, Studio, Realtime) is booted later by crbn up — see Local Dev CLI below. There is no separate "start the database" step.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh   # Rust, if not already installed
   brew install fcl cmake ninja draco                               # collision libs (+ libccd/eigen/octomap), build tools, Draco mesh compression

./apps/assembler/scripts/build-occt.sh

cargo build --release -p assembler

Local Dev CLI (crbn)

• Git worktrees — every feature branch can live in its own checkout dir, so you can switch branches without stashing.
• Per-worktree docker compose stack — each worktree gets its own Postgres / Supabase services on dynamic ports, isolated under a carbon- compose project. Routing is handled by portless (a local HTTPS reverse proxy that serves *.dev hostnames on :443 with locally-trusted certs — installed automatically on first crbn up).

Windows users: the dev CLI (crbn, setup.sh) is POSIX-only and expects WSL or Git Bash. Native cmd.exe / PowerShell shells are not supported. From a WSL/Git Bash prompt, the standard flow (./setup.sh, pnpm dev, crbn checkout …) works the same as on macOS/Linux.

Run setup.sh once to put crbn on your $PATH and install the crbn shell function (so crbn checkout can change cwd):

./setup.sh                   # writes a sentinel block to ~/.zshrc or ~/.bashrc
source ~/.zshrc              # or open a new shell
crbn                         # shows commands

Common flows:

crbn checkout sid/cool-thing       # cd into worktree (creates if missing,
                                   # auto-fetches from origin if needed)
crbn checkout -b feat/new-thing    # new branch off origin/main + worktree
crbn checkout sid/cool-thing --up  # …and boot the stack inside it
crbn checkout 760                  # fetch GitHub PR #760 into a pr-760
                                   # branch + worktree (fork PRs work too)
crbn copy                          # re-sync .env from main checkout
crbn up | down | reset | status    # per-worktree compose stack
crbn new | list | remove           # interactive worktree management

crbn up flags:

• --no-migrate — skip supabase migration up (use when schema is already current and you just want to re-boot containers fast)
• --no-regen — skip regenerating packages/database/src/types.ts + swagger-docs-schema.ts (auto-skipped when --no-migrate is set, since no schema change implies no type drift)

Environment Variables

Create an .env file and copy the contents of .env.example into it:

cp ./.env.example ./.env

Then configure each service:

Finally, boot the stack and the apps:

pnpm dev                # equivalent to crbn up — picker lets you choose ERP/MES

crbn up prints a summary box with the live URLs once the stack is healthy. Defaults look like:

| Surface | URL | | --------------- | -------------------------------------------------------------- | | ERP | https://.erp.dev | | MES | https://.mes.dev | | Supabase API | https://.api.dev | | Supabase Studio | https://.studio.dev | | Inngest | https://.inngest.dev | | Mail (Inbucket) | https://.mail.dev | | Postgres | postgresql://postgres:postgres@localhost:/postgres |

is derived from the branch name (e.g. sid-local-dev → local-dev). The main checkout drops the prefix and just uses erp.dev, mes.dev, etc. Ports for raw TCP services (Postgres, Inbucket, Inngest) are dynamic per-worktree — crbn status is the source of truth.

Academy and starter still run on classic localhost ports via pnpm dev:academy / pnpm dev:starter (they are not part of the per-worktree stack).

Logging In

For local development you don't need email or OAuth configured. crbn up seeds a smoke-test user ([email protected]) and writes [email protected] into .env.local for you. When that bypass email is set, signing in with it skips the magic link and logs you straight into the ERP:

1. Open the ERP at the URL from the crbn up summary (e.g. https://.erp.dev/login).
2. Type [email protected] into the email field.
3. Click Sign in with Email.

The bypass only applies to the exact address in DEV_BYPASS_EMAIL and only when that user is active — it's a dev convenience, not present in production. Any other email falls back to the normal magic-link / verification flow (which needs SMTP configured). To sign in as your own account instead, use the magic link and read it from the local mail catcher at https://.mail.dev.

Code Formatting

This project uses Biome for code formatting and linting. To set up automatic formatting on save in VS Code:

1. Install the Biome VS Code extension
2. Add the following to your VS Code settings (.vscode/settings.json or global settings):

"editor.codeActionsOnSave": {
  "source.organizeImports.biome": "explicit",
  "source.fixAll.biome": "explicit"
},
"editor.defaultFormatter": "biomejs.biome"

Commands

| Command | Description | | ------------------------------ | ------------------------------------------------------------------ | | pnpm dev | Boot the stack + apps (crbn up picker) | | pnpm run db:function:new | Add an edge function | | pnpm run db:migrate:new | Add a database migration | | pnpm run agent:new | Add an AI agent | | pnpm run tool:new | Add an AI tool | | crbn down | Stop the stack (keeps volumes — data preserved) | | crbn reset | Wipe the stack and start clean (destroys Postgres volume + flushes the redis db for this worktree) | | pnpm db:types | Regenerate types → packages/database/src/types.ts + functions/lib/types.ts (normally crbn up does this after applying migrations) | | pnpm generate:swagger | Regenerate swagger → packages/database/src/swagger-docs-schema.ts | | pnpm --filter | Run a command against a single workspace, e.g. pnpm --filter @carbon/react test |

Restoring a production snapshot

To restore a production database snapshot locally, use crbn restore. It handles both plain-text .backup and custom-format .dump archives, drops and rebuilds the public schema, realigns internal sequences, resets storage metadata, then applies any migrations the backup predates and regenerates types.

1. Export a backup from your production Supabase project (pg_dump or Supabase Dashboard → Database → Backups).
2. Run it from your worktree root:

crbn restore /path/to/db_cluster.backup
   # …or for .dump archives:
   crbn restore /path/to/postgres_YYYYMMDD.dump

It prompts before replacing the database. The stack must already be running (crbn up) — a restore rewrites the auth and storage schemas, which GoTrue and Storage build through their own migrations when those containers boot, so crbn restore refuses rather than restore into an uninitialized stack.

To also get local admin access, pass your production email — your account is upgraded to Admin in the companies it already belongs to and the password is reset locally:

crbn restore /path/to/backup.backup --admin-email [email protected]
   # Optional: set a custom local password (default: localpass)
   crbn restore /path/to/backup.backup --admin-email [email protected] --admin-password mypass

Useful flags: --no-scrub-emails keeps real addresses (see the warning below), --mode prod restores exactly as-is without localizing config/webhooks/integrations, --no-migrate / --no-regen skip the trailing steps, --yes skips the prompt.

> Emails are scrubbed by default — every address is rewritten to @example.test (your --admin-email is preserved so you can still log in). If you pass --no-scrub-emails, real production addresses will be present in the local DB; ensure local email sending is disabled or pointed at a sandbox (e.g. Mailpit) before triggering any email flows. > > Note: storage.objects is truncated by default, so a restore does not populate local file storage — kept rows would reference files that only exist in the source environment's backend. Pass --keep-storage-objects to retain the metadata (and the backup's buckets) anyway; downloads will still 404, but the rows are there for work that needs realistic storage volume.

The underlying script, scripts/restore-database.sh, can still be invoked directly — it takes the same options as environment variables (SCRUB_EMAILS, ADMIN_EMAIL, ADMIN_PASSWORD, RESTORE_MODE), but note it defaults to not scrubbing emails and leaves the trailing pnpm db:migrate / pnpm db:types to you.

API

The API documentation is located in the ERP app at ${ERP}/x/api/js/intro. It is auto-generated based on changes to the database.

There are two ways to use the API:

1. From another codebase using a supabase client library — JavaScript, Flutter, Python, C#, Swift, Kotlin
2. From within the codebase using our packages

From another codebase

First, set up the necessary credentials in environment variables. For the example below:

1. Navigate to settings in the ERP to generate an API key. Set this in CARBON_API_KEY.
2. Get the Supabase URL to call (this is SUPABASE_URL in your .env if hosting locally, e.g. http://localhost:54321). Set this as CARBON_API_URL.
3. Get the SUPABASE_ANON_KEY e.g. from your .env file. Set this as CARBON_PUBLIC_KEY.

import { Database } from "@carbon/database";
import { createClient } from "@supabase/supabase-js";
const apiKey = process.env.CARBON_API_KEY;
const apiUrl = process.env.CARBON_API_URL;
const publicKey = process.env.CARBON_PUBLIC_KEY;
const carbon = createClient<Database>(apiUrl, publicKey, {
  global: {
    headers: {
      "carbon-key": apiKey,
    },
  },
});
// returns items from the company associated with the api key
const { data, error } = await carbon.from("item").select("*");

From the monorepo

import { getCarbonServiceRole } from "@carbon/auth/client.server";
const carbon = getCarbonServiceRole();
// returns all items across companies
const { data, error } = await carbon.from("item").select("*");
// returns items from a specific company
const companyId = "xyz";
const { data, error } = await carbon
  .from("item")
  .select("*")
  .eq("companyId", companyId);

Migration Notes