Skip to main content

Quickstart

Prefer the full walkthrough

For the unassisted path (app init → validate → package → install), use Build your first app. This page is a shorter loop for people who already have publish credentials.

Scaffold a metadata Marketplace App. Qefro Runtime executes it — no SDK server.

ExampleDomain
restaurant-pro-runtimeReservations / menu (canonical)
real-estate-runtimeProperties / leads / viewings
shopify-runtimeProducts / customers / orders

Collection: qefro-marketplace-apps.

Prerequisites​

  • A Qefro organization with admin access to the portal (app.qefro.com).
  • The qefro CLI on your PATH.
  • A signing key for publishing: either QEFRO_SIGNING_KEY_HEX (32 bytes of hex) or a keys file containing REGISTRY_PRIVATE_KEY pointed to by QEFRO_KEYS_FILE.
Platform admin only

Publishing is restricted to platform admins (QEFRO_PLATFORM_ADMIN_IDS). Tenant and workspace admins can install published solutions; they cannot publish or yank catalog versions. See Publishing.

Step 1 — Scaffold the package​

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

Generated layout:

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

Or study the polished vertical: apps/restaurant-pro-runtime (app id restaurant-pro-runtime).

Step 2 — Write the manifest​

id: restaurant-pro-runtime
name: Restaurant Pro
version: 0.1.0
hosting: runtime
description: Table reservations and menu as a metadata Marketplace App
category: hospitality
entities:
  - table
  - reservation
  - menu_item
flows:
  - create-reservation
events:
  - reservation.created
  - reservation.cancelled
permissions:
  - workflow.execute
  - storage.read
  - storage.write
  - storage.update
  - storage.delete
capabilities:
  - theme.get
  - user.get
  - tenant.get
  - runtime.query
  - workflow.trigger
  - storage.read
  - storage.write
ui:
  name: Restaurant Pro

Do not set endpoint. Every field is documented in Manifest.

Step 3 — Declare entities​

entities/reservation.yaml (excerpt)
id: reservation
fields:
  - name: guest_name
    type: string
    required: true
  - name: covers
    type: integer
    required: true
  - name: date
    type: date
    required: true

Storage is Qefro-managed. See Managed storage.

Step 4 — Define the UI​

ui/sources.yaml
- id: reservations
  type: entity
  target: reservation
ui/widgets.yaml (excerpt)
- id: reservations_table
  type: table
  title: Reservations
  source: reservations
  options:
    rows_path: items
    columns:
      - { key: guest_name, header: Guest }
      - { key: covers, header: Covers }
      - { key: date, header: Date }

Wire navigation, pages, layouts, and theme as in Themes, Sources.

Step 5 — Add a workflow​

Same FlowRunner as every Business Flow:

workflows/create-reservation.yaml (excerpt)
id: create-reservation
name: Create reservation
trigger:
  type: conversation
steps:
  - id: ask_covers
    type: ask
    field: covers
    message: How many guests?
  - id: create
    type: tool
    tool: entity.reservation.create
    execution: runtime
  - id: done
    type: complete

Details: Workflows.

Step 6 — Validate, package, publish, install​

qefro app validate .
qefro app package .
qefro publish .
qefro app install restaurant-pro-runtime

See Validation, Packaging, Publishing, Installation.

Step 7 — Open the UI​

/app/solutions/ui/restaurant-pro-runtime/dashboard

Tables are fed by type: entity sources. Chat “book a table” starts create-reservation.

What's next​