What is Open Mercato?

Open Mercato is an open-source TypeScript framework for building business applications on Next.js and PostgreSQL. A new project does not start empty: it starts as a working back office with modules for customers, catalog, sales, warehouse, customer portal, workflows and more. The project calls itself an AI-Engineering Foundation Framework, because every generated app also ships an AGENTS.md file, rules and skills that tell coding agents such as Claude Code, Codex and Cursor where modules, data models and UI belong. The official website lists Tomasz Karwatka, Piotr Karwatka, Patryk Lewczuk and Maciej Gren as the founding team.

Distribution is npm-first. npx create-mercato-app scaffolds a standalone app with the classic, crm, wms or empty preset and installs agent instructions for the chosen tools. yarn setup then installs dependencies, applies migrations, loads demo data and either reuses existing PostgreSQL, Redis and Meilisearch services or starts them through Docker Compose. Production paths are a Docker Compose stack for a Linux VPS and a built-in Railway deploy command. Open Mercato Cloud offers browser-based development sandboxes, described as a trial workspace, not production hosting.

The latest release is v0.9.0, published October 9, 2026. It ships the second ecommerce release (an availability contract with a safety-stock-aware warehouse provider, customer groups and B2B terms, an admin UI for pricing rules and bulk-create endpoints for products and categories), moves the forms questionnaire module into the core package, makes communications two-way with Gmail history import, and consolidates a security pass on tenant and organization isolation. Version 0.8.0 (September 18, 2026) added the Agent Orchestrator, staff time tracking, a collaborative documents module and a Discord channel; 0.7.0 added the EUDR due-diligence module, warranty and RMA claims and the WMS starter preset. The monorepo main branch already declares 0.10.0, which was not yet released when this profile was checked.

Each module in src/modules/<id> bundles pages, API routes, CLI commands, translations and entities and is discovered automatically. MikroORM keeps per-module entities and migrations, an Awilix container is built per request, zod validates input and every entity carries tenant_id and organization_id. Events run locally or over Redis, and Meilisearch provides full-text search. See the architecture overview.

Open Mercato Core is MIT licensed. The @open-mercato/enterprise package, which holds MFA, SSO and Directory Sync, record locking and the Agent Orchestrator, is distributed under a separate commercial license. The README states that no manufacturing or purchasing module exists, and that the documentation does not yet cover Open Mercato Cloud, the Cezar agent IDE or the skills pipeline. Versions are below 1.0 and several releases carry migration steps. The gallery screenshots come from the README walkthrough of Kaldi and Co., a fictional coffee roaster built on the framework.

Inside the application

Open Mercato screenshots

Explore the interface. Open a screenshot to view it at full size.

View full size ↗

Open Mercato screenshot 1

Sales orders in the Open Mercato back office, from the README walkthrough of the fictional Kaldi and Co. demo app.

View full size ↗

CRM company record

A CRM company record with deal and activity summaries and assigned roles, from the fictional Kaldi and Co. demo app.

View full size ↗

Agent-built custom module

A custom Roast batches module that a coding agent built in the README walkthrough; it is an example, not a shipped module.

View full size ↗

Customer portal warranty claim

The customer portal with a signed-in cafe viewing a warranty claim and its status steps, from the Kaldi and Co. demo.

View full size ↗

Cezar running om-help

Cezar, the separate MIT agent IDE, running the om-help skill in a fresh Open Mercato app and waiting for an answer to an open question.

Source: official Open Mercato project page.

Key capabilities

Standalone app scaffolding npx create-mercato-app my-app --preset classic --agents all --init-git creates an app with demo data and agent instructions for Claude Code, Codex, Cursor and GitHub Copilot (Copilot gets instructions only, without hooks). The README asks for Docker, about 8 GB of free RAM, Node.js 24 and Yarn 4, and uses mise to install the toolchain. On Windows the documented route is WSL2. A first run in the README example took about 11 minutes to reach a working login.
Running without Docker Only PostgreSQL 15 or later is required; Redis 7 adds shared cache, queues and events, and Meilisearch 1.11 adds full-text search. The database user must be able to create the unaccent and pg_trgm extensions on the first run, and pgvector is only needed for vector search. yarn setup --no-infra uses the services configured in .env without any Docker calls. Remote database migrations require an explicit target acknowledgement flag.
CRM: companies, people and deals The customers module holds companies, people, deals with pipeline, Kanban, list and map views, roles, notes, activity logs, change logs and files. Version 0.9.0 lets a deal owner be assigned from the detail view and through a bulk Reassign owner action. Custom entities and fields are managed live from the admin without a redeploy.
Catalog and pricing rules The catalog covers categories, products, variants, prices and offers. Since 0.9.0, per-customer, per-group, quantity-tier and validity-window pricing rules have an admin UI; before that they could only be created by writing database rows. Bulk-create endpoints for products and categories pre-validate batches, support checkpoint and resume, and isolate failures per row for large imports.
Sales documents Sales channels, quotes, orders, invoices, shipments and payments share one document model. Version 0.9.0 recomputes gross totals on every price, quantity, discount or tax edit and stops an order-level undo from deleting shipments, payments and returns recorded after it. Version 0.8.0 changed the meaning of the line discount amount, which needs attention in the upgrade notes.
Warehouse and availability The wms module manages locations, inventory lots, movements and an operational dashboard, and a WMS starter preset exists for warehouse-first apps. The 0.9.0 availability contract adds a provider registry, a sell-policy module and a warehouse provider that respects safety stock. Purchasing and receiving are not included.
Customer portal and accounts Customer accounts sign in to a separate portal where they see their own claims, tasks and time reports. Portal sessions are rechecked on every API request since 0.9.0, so a revoked session stops authenticating. The README example gives one cafe a portal login in about three minutes of agent work.
Further business modules A classic app also includes shipping carriers, notifications, staff with teams and time entries, planner availability, bookable resources, warranty claims, EUDR due diligence, dashboards, attachments, documents, audit logs, translations and API keys. The forms module with versioned definitions, public runners, PDF snapshots and GDPR anonymization moved into the core package in 0.9.0. The module overview lists what each one provides.
Workflows and business rules Workflows define custom data lifecycles per tenant or team, and business rules can call Open Mercato actions. The README example adds a rule that notifies the head roaster when roasted stock drops below 20 kg. Version 0.8.0 lets workflows invoke agents from the Agent Orchestrator, which is part of the commercial enterprise package.
Multi-tenancy and RBAC Entities carry tenant and organization identifiers, organizations form trees, and access is granted through named features per role and per user. Routes declare requireAuth, requireRoles and requireFeatures metadata, and missing features return 403. Super administrators bypass feature checks, so that role needs to stay limited.
Field-level encryption Tenant data encryption uses per-tenant data keys, optionally stored in HashiCorp Vault, and deterministic hashes keep lookups working on encrypted columns. The encryption guide states that this is at-rest protection, not a read-side access control, and that vector embeddings are stored unencrypted. Map changes apply only to data written afterwards.
REST API with OpenAPI API routes are discovered from each module and documented at /backend/docs, served from /api/docs/openapi. Machine clients authenticate with an X-Api-Key header; keys inherit the roles assigned to them and carry their tenant and organization scope. List endpoints default to 50 items per page. The REST API overview covers authentication, scoping and conventions.
In-app AI assistant and MCP server Assistants open inside admin pages, scoped by module, permissions and tool allowlists, and every write is staged behind an approval card before data changes. Operators can tune prompts and disable tools per tenant. An MCP server exposes tenant tools to Claude Code and other clients over HTTP and binds to loopback by default; the dev mode reads one API key at startup and runs with superadmin-equivalent access.
Agent harness and skills A new app ships 15 local Open Mercato skills and 15 delivery skills from open-mercato/skills, pinned to a commit. Every task starts with om-help, which returns the ordered guides, skills and checks without writing code. Specs live in .ai/specs/, and agents stop at open questions before implementing.
Cezar agent IDE Cezar is a separate MIT-licensed tool started with npx cezar-run, which opens on port 4321 and runs each task in its own git worktree. It supports seven agent CLIs, including Claude Code, Codex, GitHub Copilot CLI and OpenCode, can start tasks on a schedule or on GitHub events, and never merges on its own. It needs Node.js 20 or later and one logged-in agent CLI.
Module packaging and catalog create-mercato-module turns an app module into an npm package and installs it in another app. Open Mercato Modules lists official and community modules with license and nightly install results. New apps refuse third-party npm versions younger than five days through a Yarn age gate.
Communications and channels The communications hub handles IMAP and Gmail mailboxes, with history import widened to 3650 days or 50000 messages in 0.9.0, plus a Discord channel and mobile push through FCM, APNs and Expo. Since 0.8.0, outbound system email goes through provider packages such as Resend or SES, and a standalone app must enable one or outbound email stops.
Production deployment The VPS guide runs the app, PostgreSQL, Redis and Meilisearch through Docker Compose on Ubuntu 22.04 or later with Docker 24 or later and at least 2 GB of RAM, 4 GB recommended. The stack refuses to start without a JWT_SECRET of at least 32 characters. yarn mercato deploy railway --dry-run previews a Railway deployment that checks /api/healthz.
Open Mercato Cloud sandboxes Hosted sandboxes include the app templates, VS Code in the browser, a web terminal, Claude Code, Codex and Cezar, with PostgreSQL and Redis but no Docker. The site lists a 7-day trial with $5 of AI tokens, a Developer plan at $95 per seat per month after a $75 first month, and an Enterprise plan at $1,400 per month. Work leaves the sandbox through a GitHub repository or an export archive.

Where Open Mercato fits

Starting a B2B back office from a preset

Choose the classic preset when the business needs customers, catalog, sales, warehouse and a portal, crm for a sales-only app, wms for warehouse work or empty for a bare shell. Run yarn setup, open http://localhost:3000/backend as localhost rather than an IP address, and sign in with the demo administrator. Check that Customers lists demo companies and Sales lists demo orders before adding anything. Then compare your processes with the module list and write down what is missing, because that gap becomes the first custom module.

Building the missing module with a coding agent

Ask the agent to run om-help with two or three sentences about the business, then write a spec with om-spec-writing and stop at its open questions. After approval, om-implement-spec builds the module phase by phase. Review the SQL from yarn db:generate before allowing yarn db:migrate, run yarn mercato auth sync-role-acls so roles see the new page, and restart the dev runtime once. The full check (generate, typecheck, lint, design-system check, tests and build) should exit 0 before the work is merged.

Using the framework as a headless business backend

Keep the admin for operators and build a custom frontend against the generated REST API. Mint an API key under Admin, Security, API keys or with the CLI, assign it only the roles the client needs, and send it in the X-Api-Key header. Confirm tenant and organization scoping with a key from a second organization, and read the OpenAPI document at /backend/docs rather than guessing payloads. The API overview documents pagination and the organization switcher.

Handing routine work to agents unattended

Run npx cezar-run in the app root and create one task per backlog item, for example an issue-to-pull-request task or a review task for each new pull request. Automations can start tasks on a schedule or on GitHub events once the app has a GitHub remote. Neither Cezar nor the shipped skills merge code, so a person still reads the diff and merges. Check the token cost and run time that Cezar shows per task before scaling the number of automations.

Deploying and upgrading a production instance

Work through the production readiness checklist, then deploy with Docker Compose on a VPS or with the Railway command. Set strong PostgreSQL, Meilisearch and JWT secrets and put TLS in front of port 3000. For upgrades, run yarn up '@open-mercato/*', yarn generate and the migrations, refresh the pinned skills and agent harness, and read the upgrade notes first: 0.9.0 requires PostgreSQL extensions for catalog search and an encryption-map migration.

Protecting customer data

Enable tenant data encryption with a Vault-backed key store or a dedicated fallback key, and declare encrypted columns in the encryption maps of each module. Gate pages and routes that return sensitive fields with ACL features, because encryption does not restrict who can read decrypted values. Keep the MCP server on loopback and never expose the dev mode, which reuses one superadmin-equivalent key. Report vulnerabilities to the address in the project security policy.