Getting started with Marketplace

Install the app, set AI environment variables, list trusted stores, run checks, complete the first-run setup, and deploy.

Try the hosted copy first: marketplace.openship.org.

Requirements

Node.js 20.9 or later (the app uses Next.js 16).
npm.
Outbound HTTPS access to the stores you list and to your AI provider.
At least one public HTTPS Openfront E-commerce or Openfront Restaurant store.

Marketplace has no database. Unlike most Openfront products, current source does not read DATABASE_URL, SESSION_SECRET, or any S3_* variable. There are no migrations to run and no first admin user to create. If you see empty features/keystone, features/platform, migrations, or app/dashboard folders in a local checkout, they hold no files and nothing in the app uses them.

Install

git clone https://github.com/openshiporg/marketplace.git
cd marketplace
npm install

Environment

Copy .env.example to .env. These are the only variables the code reads:

# Shared ("Global") AI mode. All buyers use this OpenRouter key.
OPENROUTER_API_KEY=replace-with-your-openrouter-key
OPENROUTER_MODEL=openai/gpt-4o-mini
OPENROUTER_MAX_TOKENS=4000

# Set to true to hide the Local option and force shared mode.
MARKETPLACE_DISABLE_LOCAL_AI=false

# Optional comma-separated allowlist for custom OpenAI-compatible endpoints.
# MARKETPLACE_CUSTOM_AI_ORIGINS=https://proxy.example.com

What each one does:

Variable	Effect
`OPENROUTER_API_KEY`	Key used in shared mode. Shared mode is offered only when this and `OPENROUTER_MODEL` are both set.
`OPENROUTER_MODEL`	Model used in shared mode. The completion route falls back to `openai/gpt-4o-mini`.
`OPENROUTER_MAX_TOKENS`	Output token cap in shared mode. Defaults to 4000. Must be a positive whole number or shared requests fail.
`MARKETPLACE_DISABLE_LOCAL_AI`	`true`, `1`, `yes`, or `on` turns off "bring your own key" mode and the `/api/ai-models` route.
`MARKETPLACE_CUSTOM_AI_ORIGINS`	Restricts custom AI endpoints to these origins. When unset, any public HTTPS origin is allowed.

All variables are optional. With none set, each buyer must enter their own OpenRouter key or a custom OpenAI-compatible endpoint.

List your stores

Edit marketplace.config.json in the repository root. This file is the server-side allowlist. The server only talks to stores in it.

[
  {
    "baseUrl": "https://store.example.com",
    "platform": "openfront"
  },
  {
    "baseUrl": "https://restaurant.example.com",
    "platform": "openfront-restaurant"
  }
]

Rules the code enforces:

baseUrl must be HTTPS with no username, password, query string, or fragment.
platform must be openfront or openfront-restaurant to work. Other names parse but have no adapter.
id is optional. If you include it, it must equal the derived ID (source-v2-<platform>-<encoded baseUrl>). A mismatched ID makes the server skip that entry.
Duplicate endpoints are skipped.
name is optional and overrides the store name shown in the UI.

The GraphQL endpoint is baseUrl plus /api/graphql for both supported platforms.

Buyers can remove, re-add, and rename stores in the in-app store editor. They cannot add a store that is not already in marketplace.config.json.

Run locally

npm run dev

Open http://localhost:3000.

First-run setup

There is no server-side onboarding or seed. The first visit opens a setup dialog in the browser:

Marketplace name and theme. Default name is "Common Goods". Themes are clay, forest, and midnight. Saved in localStorage only.
AI mode. "Global" uses the server's OpenRouter key (shown only when it is configured). "Local" asks for a provider (OpenRouter or a custom OpenAI-compatible endpoint), a model, an API key, and a token limit.
Risk confirmation. The buyer confirms before the chat is enabled.

Local keys are stored in the buyer's browser and sent with each /api/completion request.

Checks

npm test
npm run test:security
npm run test:platform
npm run typecheck
npm run lint
npm run build

npm test runs the Node test files in tests/. They cover source IDs, request size limits, private-address blocking, redirect refusal, MCP UI action rules, model output projection, chat history storage, and token budgets. There are no browser end-to-end tests.

Deploy

The app runs on any Node.js host that supports Next.js server routes. The README includes Vercel and Railway buttons.

For a deployment you need:

the AI variables above in your host's secret store (or none, for bring-your-own-key only);
a reviewed marketplace.config.json built into the artifact;
outbound HTTPS from the server to every listed store and the AI provider.

The completion route calls the app's own /api/mcp-transport/http endpoint. It builds that URL from the x-forwarded-host (or host) and x-forwarded-proto request headers, so your proxy must set them correctly.

External MCP clients can connect to https://your-host/api/mcp-transport/http. Product, cart, and checkout cards need a client that renders MCP UI resources.

Getting started with Marketplace

On this page