Open Mercato

Open Mercato Core is MIT licensed

Open Mercato - the AI-Engineering Foundation Framework. Start with 80% done.

Open Mercato is an open-source TypeScript framework on Next.js and PostgreSQL. It ships ready business modules for CRM, ERP, commerce and more, so a new app starts as a working back office. It is built for AI coding agents: Claude Code, Codex and Cursor get the rules and skills that say where code goes, and Cezar, the agentic development IDE, runs each task in its own git worktree and streams it live. It is for teams and developers building business apps and backends, and for business owners who want one.

npx create-mercato-app my-app

No terminal? Open Mercato Cloud gives you the same app in the browser, with Claude Code, Codex and Cezar already inside (account required).

Prefer to delegate? Paste this line into Claude Code, Codex or Cursor:

Read https://raw.githubusercontent.com/open-mercato/open-mercato/main/README.md and follow it for my project, stage by stage. Stop and ask me at every "You decide" and at every open question.

[!NOTE]

For AI coding agents. To build an app, scaffold it with npx create-mercato-app --preset --agents all --init-git (or a comma-separated list of claude-code, codex, cursor, github-copilot) and never clone this repository unless the human wants to change Open Mercato Core. If the request is ambiguous, such as "install this repo", ask that one question first. After scaffolding, the app's own AGENTS.md takes over and every task starts with om-help. Work one stage at a time: ask the You decide question and offer the bold default, do Run, confirm every Done when box. Stop at every "You decide" and at the spec's Open Questions.

Quick start · Cloud · Cezar · Modules · Docs · Tutorials and videos · Discord · Contributing

_{Kaldi & Co. is a fictional specialty coffee roaster in Lisbon. The screens on this page are from the app built with the four stages below, with the roaster's own demo data loaded through the API.}

What is Open Mercato

AI code assistants generate code. They do not decide where it goes, how it is layered, or whether it stays consistent across 30 or 50 engineers in a team. Open Mercato gives them a foundation that does:

• Architecture-aware AI harness. Every app ships an AGENTS.md and skills that tell the agent where code, modules, data models and UI belong, how to troubleshoot and how to upgrade, from a data table or a design-system form up to a whole feature with unit and integration tests. The open-mercato/skills collection adds code review, ticketing and debugging.
• Spec-first. Specs live next to the code in .ai/specs/ and drive the agent's work: plan, approve, then implement.
• Start with 80% done. Dozens of business modules already work together: customers, catalog, sales, warehouse, portal, workflows and more (what's in the box).
• Unattended when you want it. Cezar runs the same skills in parallel, on a schedule or on GitHub events, and never merges on its own.
• No lock-in. You own the code. The core is MIT with no per-seat licence; enterprise modules are licensed separately.

Get started

Pick your row. Everyone who builds an app goes through the same four stages, and each stage has the same shape: You decide (a question with a bold default), Run (commands or the exact prompt), Done when (checks you can tick), then a screenshot from the Kaldi run. The whole run, from npx to a working module with a business rule and a cafe login, took one agent evening: about 2 hours 10 minutes of wall time, the long parts being the first install and the module build.

| You are | Start with | Then | |---|---|---| | A business owner without a terminal | Open Mercato Cloud | the In the Cloud line of each stage, or a Certified Partner Agency | | A developer | Minute 10 in your terminal | Hour 1, Day 1, Month 1 | | An AI coding agent | the note at the top of this page | every stage in order, stopping at each You decide | | A module author | Build and publish a module | create-mercato-module, then list it in Open Mercato Modules | | A core contributor | Change Open Mercato Core | CONTRIBUTING.md |

No terminal: Open Mercato Cloud

Open Mercato Cloud is a hosted trial workspace (Beta) with the app already initialised. Inside you get:

• the templates crm, classic or empty, demo users, a View as role switcher and a live preview;
• VS Code in the browser and a web terminal;
• Claude Code and Codex, on managed credits by default or on your own subscription (claude auth login --claudeai, codex login --device-auth);
• Cezar, preinstalled as the AI Coding Agent tab (Beta): the default way to drive the agent here;
• PostgreSQL and Redis. There is no Docker inside, and it is not production hosting.

Minute 10: a running back office

You decide: which starter? classic (CRM, catalog, sales, warehouse, portal, demo data) · crm · wms · empty. Which agents? all (Claude Code, Codex, Cursor and GitHub Copilot, which gets instructions only, no hooks) · one of them.

Run in a terminal, as is. You need Docker running (Docker Desktop, OrbStack or Colima) and about 8 GB of free RAM; mise installs Node.js 24 and Yarn 4 for you. On Windows use WSL2 and see Developing on Windows. All options: installation guides.

curl https://mise.run | sh && export PATH="$HOME/.local/bin:$HOME/.local/share/mise/shims:$PATH"
mise use -g node@24 yarn@4      # Node.js 24 and Yarn 4; skip both lines if you already have them
npx create-mercato-app my-app --preset classic --agents all --init-git
cd my-app
docker compose up -d --wait     # PostgreSQL 17 with pgvector, Redis 7, Meilisearch
yarn setup                      # installs, creates .env, migrates, seeds demo data, starts the dev runtime and keeps running

A plain npx create-mercato-app my-app asks these questions plus Git init (its agent default is Claude Code). Without a terminal it silently picks classic, claude-code and no git, so agents always pass the flags and run yarn setup in the background. If docker compose fails, offer Open Mercato Cloud instead. To keep mise after this terminal closes, add eval "$(~/.local/bin/mise activate zsh)" (or bash) to your shell profile. Pushing to GitHub is optional and comes later, in Day 1.

In the Cloud: sign in or request access (registration may be closed, see the waitlist note), create a sandbox from the classic template, wait until it shows Running, then click Open app.

Done when

• [ ] the terminal prints Backend URL http://localhost:3000/backend; the logins are [email protected] / secret, also [email protected] and [email protected] with the same password (the full box is in .mercato/logs/*-dev-setup-runner.log, or run yarn setup --verbose)
• [ ] you open http://localhost:3000/backend and sign in as [email protected] / secret (Cloud: Open app, then View as Admin). Open it as localhost, not 127.0.0.1 or the machine's IP: the dev server serves its scripts to localhost only, so other hosts get a page that never finishes loading (on a remote box, use an SSH tunnel)
• [ ] for agents: curl -s -o /dev/null -w '%{http_code}' localhost:3000/login prints 200 and .agents/skills/om-help exists (if not, run yarn install-skills)
• [ ] Customers lists demo companies and people, and Sales lists demo orders

Start the Coding Agent

Your app is running. Now start the agent that builds on it. The quickest way is your agent's CLI in the app folder: claude, codex or agent (Cursor CLI, formerly cursor-agent). For the best developer experience, use Cezar, the open-source (MIT) agentic development IDE: you type a task, Cezar runs the agent in its own git worktree and streams the run live, with its changes, commits and a terminal one click away.

npx cezar-run                                        # in the app folder; opens Cezar at http://localhost:4321

It works with seven agent CLIs: Claude Code, Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Junie and pi, runs the om-* skills in parallel, on a schedule or on GitHub events, and never merges on its own.

npx cezar-run run "<task>"                           # one task, headless
npx cezar-run server-install --platform ubuntu-vps   # always on, 24/7 (or --platform macosx-ngrok)

• What it does: locally each task runs in its own git worktree. Automations start tasks on a schedule, when a GitHub PR is opened (needs the GitHub remote from Day 1), on reviews or issues, or from Jira and Linear, and a task can spawn child tasks.
• What it needs: Node.js 20+ and one agent CLI that is already logged in. git and gh are optional; you need them for pull requests and the GitHub tab.
• Where it runs: in any repository (it is not specific to Open Mercato), on your laptop, on a server, or in Open Mercato Cloud as the AI Coding Agent tab (Beta).

Build the missing 20% with your agent

Buy vs. build? Now, you can have best of both. Use Open Mercato enterprise-ready business features like CRM, Sales, OMS, Encryption, and build the remaining 20% that really makes the difference for your business. Watch: Start with 80% done

Your app already knows how it is built. Start every task with om-help: /om-help in Claude Code, $om-help in Codex, or the sentence Use om-help: in any agent. It only routes: it returns the ordered list of guides and skills, why each one is needed, the delivery shape and the smallest set of checks. It never writes code, plans your business or loads data.

Before you build, check whether it already exists: search Open Mercato Modules, the catalog of official and community modules. Each module page shows what the module adds, its license, the Open Mercato versions it installed on in a nightly run, and the exact install command (yarn mercato module add for a module, yarn add for a library or adapter).

Hour 1: a route and a spec

You decide: what does your business need that the demo does not do? Use the Kaldi & Co. example as it is to see the flow, or describe your own business in two or three sentences. Kaldi's answer: "We buy green-coffee lots and roast three blends, Alfama Espresso, Belem Filter and Douro Decaf. We sell wholesale to about 40 cafes that order weekly. We lend espresso machines and send technicians, and every lot needs origin evidence under the EU deforestation rules."

Run: paste this into your agent.

Use om-help: <your sentences>. Tell me which guides and skills this needs. Then write a spec with om-spec-writing for the first slice and stop at Open Questions. No code yet.

In the Cloud: open the AI Coding Agent tab and start a task with the same prompt, or run claude (or codex) in the web terminal and paste it there.

Done when

• [ ] om-help returned the ordered guides and skills and the checks to run (about 3 minutes in the Kaldi run)
• [ ] a spec exists at .ai/specs/-.md (about 10 minutes)
• [ ] you answered every Open Question; the agent waits there until you do

| Kaldi needs | Already in the box | |---|---| | Green-coffee lots and stock | Warehouse (wms) and Catalog | | Suppliers and cafes | Customers | | Three blends | Catalog | | Weekly wholesale orders | Sales, plus the customer portal and customer accounts | | Technicians | Staff and Planner (partial: no dispatch) | | Machine repairs | Warranty claims (partial: not field service) | | Origin evidence for every lot | EUDR | | Purchasing and receiving, standing weekly orders, machine loans and service visits, a lot-to-evidence gate | Not yet (missing in the run) | | Roast batches: lot in, profile, bags out | Nothing. This is your 20%. |

Day 1: the missing 20% as a module

You decide: read the spec. Approve it · change it. Where should the work land? locally, phase by phase · as a pull request. If the spec still lists open questions, the agent refuses to build and asks you to answer them; "use the recommended defaults" is a valid answer.

Run: paste this into your agent.

Implement the approved spec with om-implement-spec, phase by phase. Show me the SQL from yarn db:generate and ask me before yarn db:migrate. Then run the full check.

As a pull request instead: /om-auto-implement-spec .ai/specs/-.md opens its own PR. It needs a GitHub remote, which you add once with git add -A && git commit -m "Initial commit" && gh repo create --private --source=. --remote=origin --push (gh 2.82.1+ and jq); without one, agents report "PR delivery unavailable" and work locally. Either way, this is what the agent runs, so you can follow along:

# creates src/modules/roast_batches/ and adds to src/modules.ts:
  enabledModules.push({ id: 'roast_batches', from: '@app' })
yarn generate
yarn db:generate                    # writes the migration: review the SQL, the agent asks you
yarn db:migrate                     # only after your yes
yarn mercato auth sync-role-acls    # without it, even admin does not see the new page
then stop and start yarn dev once: the running dev runtime does not pick up a new entity,
and the new API answers 500 until it restarts (the menu entry can take up to 5 minutes, the role cache)
yarn generate && yarn typecheck && yarn lint && yarn ds:check && yarn test && yarn build
yarn test:integration:ephemeral     # integration tests, needs Docker

In the Cloud: the same prompt in the AI Coding Agent tab or the web terminal. PostgreSQL and Redis already run, so there is nothing to start, and the new page appears in the live preview.

[!IMPORTANT]

Rules for agents in an app. Never edit node_modules or .mercato/generated/**. Never run yarn db:greenfield, yarn reinstall or yarn setup --reinstall without asking. Ask before yarn db:migrate. Follow the app's AGENTS.md.

Done when

• [ ] Roast batches is in the admin menu with a list and a detail page
• [ ] its REST API appears under /backend/docs (served from /api/docs/openapi) and is guarded by the new permissions
• [ ] the full check above exits 0 (about 45 minutes in the Kaldi run, from approved spec to green module tests, including the restart above).

Month 1: unattended work with Cezar, upgrades, production

You decide: what runs without you? a review of every new pull request · issues to pull requests · nothing yet. Where does production run? Railway · a VPS. Never in the Cloud sandbox.

Run

1. Finish the first slice with your agent:

Use om-help: add a business rule "Roasted stock below 20 kg: notify the head roaster" and give one cafe a login to the customer portal.

1. Hand the backlog to Cezar: run npx cezar-run in the app root and create one task per item, typed as you would to your agent: /om-auto-fix-issue 123 (issue to PR), /om-auto-create-pr "" (one change as a PR), /om-auto-review-pr (review), /om-auto-qa-pr (QA in a browser). Add an automation that starts a review task when a GitHub PR is opened. For 24/7, use npx cezar-run server-install --platform ubuntu-vps. Filing issues from a plain description and the feature route of /om-auto-fix-issue without an existing spec need yarn install-skills --with automation.
2. You merge: read the PR, then gh pr merge . Cezar and the skills your app ships never merge.
3. Upgrade:

yarn up '@open-mercato/*' && yarn generate && yarn db:migrate   # agents ask before migrating
   yarn install-skills --update                                    # refresh the pinned skills
   yarn mercato agentic:init --update-harness                      # refresh the agent harness

For a version jump, use the matching om-auto-upgrade--to- skill (opt-in; yarn install-skills --list shows the tiers).

1. Ship: yarn mercato deploy railway --dry-run, then yarn mercato deploy railway (needs a Railway account token; the deploy checks /api/healthz; Railway guide), or follow the VPS guide.

Done when

• [ ] the rule is listed under Business rules and the cafe signs in to the portal, where it sees its own claims and tasks (about 3 minutes in the Kaldi run)
• [ ] Cezar shows each task with its pull request, and you merged only what you reviewed
• [ ] after an upgrade, the full check from Day 1 is green again
• [ ] your production domain answers

Build and publish a module

Built something other apps need too? create-mercato-module turns one module of your app into an npm package, optionally with its own GitHub repository, and installs it in any other Open Mercato app. List the package in Open Mercato Modules so other developers and their agents find it before they build the same thing.

You decide: a new module or one you already built? new · existing (skip init). A dedicated GitHub repository for it? yes, public · no.

Run in the app folder after yarn setup (keep it running to check the module at /backend/visits):

npx create-mercato-module init visits      # creates src/modules/visits and registers it; skip for an existing module
build the feature with your agent, then in a second terminal:
npm login
gh auth login                              # only for the dedicated GitHub repository
npx create-mercato-module publish visits   # asks for the package name, version and repository, publishes after you retype the name

List it: open https://modules.openmercato.com/submit?npm=@your-name/mercato-visits. The page checks the package, its license and the date a fresh app can install it, builds the catalog entry and opens GitHub with the file filled in; commit it and open the pull request. After the merge the catalog reads the module from its published source and installs it every night in a fresh app.

In the receiving app: npx create-mercato-module install @your-name/mercato-visits, or the exact install command from the module page in the catalog. A new app refuses third-party npm versions younger than 5 days (npmMinimalAgeGate in .yarnrc.yml; while a fresh release is still inside the gate, the module page shows its Installable from date), so install a fresh release from its GitHub repository instead: npx create-mercato-module install your-name/mercato-visits (needs gh auth login; agents add --approve-git-repository).

Done when

• [ ] npm view @your-name/mercato-visits version prints the version you published
• [ ] in the receiving app, the module's page opens under /backend
• [ ] after the listing pull request is merged, https://modules.openmercato.com/m/@your-name/mercato-visits shows the module

Change Open Mercato Core

You only need this repository to change Open Mercato Core. To build a product, use npx create-mercato-app above.

You decide: does the change touch packages/enterprise/? No, it stays outside · yes (stop: that folder is closed to external authors, the Enterprise Contribution Guard).

Run (plan for about 20 GB of disk and 16 GB of RAM):

npx @open-mercato/starter    # clones main into ./open-mercato, installs, starts the containers and the dev runtime
in a second terminal:
cd open-mercato
yarn install-skills          # optional: this repo's local skills plus the shared collection

Already have a clone or a fork? Run yarn om inside it instead; manual steps are in CONTRIBUTING.md.

Done when

• [ ] http://localhost:3000/backend answers from the clone
• [ ] your branch starts from main and your pull request targets main

What's in the box

Use cases

• Commerce: B2B ordering portals, CPQ and quotes, commerce backends.
• Headless backend: use Open Mercato as a ready-made business backend with a fully custom frontend, through generated REST APIs with OpenAPI docs (API reference).
• CRM: customers, deals and pipelines, flexible custom fields.
• ERP: orders, inventory (WMS), staff, resources and service delivery.
• Self-service portals for customers and partners, and workflows for custom data lifecycles per tenant or team.

Highlights: modules are auto-discovered and can be overridden without forking; custom entities and fields are managed live from the admin; multi-tenancy with organization trees; feature-based RBAC per role and per user; hybrid JSONB indexing and caching across base and custom fields; domain events with persistent subscribers, local or on Redis. Stack: Next.js (App Router), TypeScript, PostgreSQL, MikroORM, zod and Awilix.

Architecture: a module in src/modules/ bundles pages, APIs, CLI commands, translations and entities, and is auto-discovered. MikroORM keeps per-module entities and migrations, with no global schema. An Awilix DI container is built per request, and a module's di.ts registers or overrides services. Entities carry tenant_id and organization_id. Security comes as outcomes: role-based access per route and API, validated input, hashed passwords, JWT sessions and an audit log. Read the Open Mercato architecture overview.

AI assistant: focused assistants open inside the admin pages, scoped by module, permissions and tool allowlists, and every write is staged behind an approval card before data changes. Use the global launcher or embed in module pages; operators tune prompts, downgrade mutation policies and disable tools per tenant without redeploying. Read the AI assistant overview and the MCP server guide.

Encryption: tenant-scoped, field-level encryption that stays transparent to CRUD and APIs. Admins choose which system and custom columns are encrypted, and deterministic hashes keep lookups working. Read the encryption guide.

Custom CLI and modules: modules can expose their own commands as yarn mercato (CLI reference). Open Mercato Modules lists official and community modules with their anatomy and nightly install results, and yarn mercato eject --list shows the modules you can copy into your app and own fully.

Agent skills: a new app ships 15 local skills from Open Mercato and 15 delivery skills from open-mercato/skills, pinned to a commit and installed for Claude Code, Codex or Cursor. The full collection is stack-agnostic and covers spec writing, autonomous PR creation, code review, CI stabilization, integration testing and merge management, and the om-* skills are moving there.

• In an app: yarn install-skills --list shows the tiers, --with automation adds the opt-in tier, --update refreshes the pin.
• In any other repository: npx skills add open-mercato/skills --skill '*', then run the collection's one-time pipeline setup skill, as its README describes.
• In this monorepo: yarn install-skills.

Learn: docs and videos

Docs at docs.openmercato.com: Installation · Standalone app · User guide · First app tutorial · Customizing a standalone app · Architecture · Modules · API reference · CLI reference · Troubleshooting. The docs do not cover Open Mercato Cloud, Cezar or the skills pipeline yet; this page does.

Videos on the Open Mercato YouTube channel:

• Start with 80% done with Open Mercato · Building an app from scratch using autonomous skills · Building a landing page with a custom, encrypted admin panel
• Building a standalone app on Linux and macOS · How to set up Open Mercato on Windows · Open Mercato Cloud tour · Cezar demo
• For non-developers: Free video course for non-developers, built on Open Mercato Cloud (in Polish)

Community and support

• Discord: talk to the team and other builders on the Open Mercato Discord.
• Contributing: contributions of all sizes are welcome, from fixes and docs to new modules. Read CONTRIBUTING.md, open pull requests against the main branch, and use Issues or Discussions. Refer to AGENTS.md for deeper guidance on architecture and conventions when extending modules.
• Hall of Fame: meet the Open Mercato Agentic Hackathon champions.
• Planning a project? Do not go it alone: write to [email protected] and we will connect you with one of our Certified Partner Agencies. Our Partnership Program certifies software consultancies that actively use and contribute to Open Mercato.

Open Mercato is proudly supported by Catch The Tornado.

License and enterprise

Open Mercato Core is and always will be MIT Licensed, fully Open Source. See LICENSE.

Enterprise features ship in @open-mercato/enterprise (packages/enterprise) under a commercial license outside the MIT open-source scope; the Enterprise Subscription is described in the enterprise README. Contact us to get support for your implementation: [email protected]