Skip to main content

Build your first app

The default Qefro Marketplace path is metadata, not an SDK server:

qefro app init restaurant-pro
  → customize entities / workflows / ui
  → qefro app validate
  → qefro app package
  → qefro app install
  → Qefro Runtime (UI, storage, FlowRunner, CRM, Automation)

You do not write a /qefro process to ship Restaurant, Clinic, Real Estate, Booking, or CRM apps. Connecting an existing ERP / POS / CRM uses the SDK — a separate story.

What you will build​

A Restaurant Pro style app: tables, reservations, menu, a staff UI, and a conversation flow that books a table. The reference package is restaurant-pro-runtime (app id restaurant-pro-runtime, hosting: runtime).

qefro app init scaffolds the same shape with a generic record entity. Rename nouns to match your vertical, or copy the Restaurant Pro Runtime tree.

ReferencePathApp id
Collectionqefro-marketplace-apps—
Restaurant Pro Runtimeapps/restaurant-pro-runtimerestaurant-pro-runtime
Real Estate Runtimeapps/real-estate-runtimereal-estate-runtime
Shopify Runtimeapps/shopify-runtimeshopify-runtime

Prerequisites​

  1. qefro CLI on your PATH

    cd qefro-plugin-platform/services/qefro-cli
    cargo install --path .

  2. Publish credentials (only for publish / install against a live stack — see Publishing):

    EnvPurpose
    QEFRO_SOLUTION_URLsolution-service base URL
    QEFRO_PUBLISHER_IDUUID in QEFRO_PLATFORM_ADMIN_IDS
    QEFRO_SIGNING_KEY_HEXEd25519 private key (32-byte hex) matching catalog trust anchors
    QEFRO_TENANT_ID / QEFRO_ORGANIZATION_IDFor qefro app install
    QEFRO_INTERNAL_BEARERWhen service auth is enforced
Partner publish

Today, catalog publish is platform-admin only. Tenant admins install; they do not publish. Ask your Qefro contact for a publisher UUID + signing key, or use a local stack with QEFRO_PUBLISH_OPEN=true. See Marketplace.

No Node.js runtime is required for hosting: runtime apps.

Step 1 — Scaffold​

qefro app init restaurant-pro --name "Restaurant Pro"
cd restaurant-pro

(qefro app init is an alias of qefro create-app. It always scaffolds a metadata Marketplace App.)

Generated layout (actual CLI output):

restaurant-pro/
├── manifest.yaml
├── entities/
│   └── record.yaml
├── workflows/
│   └── create-record.yaml
└── ui/
    ├── navigation.yaml
    ├── pages.yaml
    ├── widgets.yaml
    └── sources.yaml

To study the full hospitality package instead of the generic stub, copy docs/examples/restaurant-pro-runtime/ — that tree adds table, reservation, menu_item, themed pages, and create-reservation.

Step 2 — Make it your domain​

You do not need a new backend. Change YAML:

  1. Entities — fields and types under entities/. Storage is Qefro-managed; you never open a database.
  2. Workflows — ask → tool (entity.<id>.create, execution: runtime) → complete. Same FlowRunner as every Business Flow.
  3. UI — pages, widgets, type: entity sources. Use host: contacts and host: automations for platform CRM surfaces.
  4. Manifest — entities:, flows:, events:, triggers, conversation_slots.

Rules that never change:

  • No src/ and no /qefro endpoint on hosting: runtime.
  • No direct database or storage/* from YAML.
  • WhatsApp number comes from the workspace channel, not install settings.
  • Same package version for every tenant.

Step 3 — Validate​

qefro app validate restaurant-pro
# alias of: qefro dev restaurant-pro

Expect hosting=runtime and “metadata package, no SDK process”. Fix errors before packaging.

Step 4 — Package and publish​

export QEFRO_SOLUTION_URL=https://…          # or http://127.0.0.1:8105
export QEFRO_PUBLISHER_ID=<admin-uuid>
export QEFRO_SIGNING_KEY_HEX=<32-byte-hex>

qefro app package restaurant-pro
# alias of: qefro solution build restaurant-pro

qefro publish restaurant-pro

Success returns a signed dist/package.json (name, version, checksum). Details: Publishing.

Runtime apps are not container images. Qefro Runtime executes the installed metadata.

Step 5 — Install​

From the Admin Console (Applications → Marketplace → Install), or CLI:

export QEFRO_TENANT_ID=…
export QEFRO_ORGANIZATION_ID=…

qefro app install restaurant-pro --version 0.1.0

Then in the portal:

  1. Open the workspace → Installed solutions.
  2. Settings → Customer channels → connect WhatsApp if you need chat.
  3. Open the solution UI (tables, forms, Contacts, Automations).
  4. In chat, try a declared intent (e.g. “book a table”).

Tenant install docs: Installation.
Catalog discovery: Marketplace.

Acceptance checklist​

You are done when all of these pass without writing an SDK server:

  • qefro app init … produced a metadata tree
  • qefro app validate reports hosting=runtime
  • qefro app package succeeds
  • Publish returns 201 (platform admin)
  • Install appears in Marketplace / Installed
  • Staff UI lists entity records
  • Chat or a form completes one flow on FlowRunner
  • Contacts / Automations host pages open (if declared)

Connecting an existing system instead​

If the system of record is already an ERP, POS, or CRM (Focus, Yaaz, ABM):

External system → Qefro SDK → /qefro → Qefro Runtime

That is External SDK Connection, not this tutorial.

Next​

GuideWhen you need it
restaurant-pro-runtimeFull hospitality YAML
real-estate-runtimeSecond vertical
Runtime vs SDKWhich path you are on
PublishingSigning, versions, yank
MarketplaceHow tenants find and install
EventsTool vs Event vs Flow vs Automation
TroubleshootingCommon failures