Apps v2

Build a web UI over Workflow-backed logic, test it inside the Flowgear Console, then publish it to the Sites where it is needed.

Start with Flowgear Apps for the architecture and App security model for the frontend, API-key, Workflow, origin, and release boundaries.

We recommend using an AI coding agent from an IDE or editor. The agent can edit the frontend repository and use Builder MCP to discover, build, and test the backing Workflows.

Download the sample App

In the Console, open Settings → Manage Apps, then click Download a sample App.
Select the development Site and Test Environment.
Optionally select a compatible Cookie-based API Key. When selected, the download includes an OpenAPI description of the Workflows permitted by that key.
Select the OpenAPI version, then click Download.
Extract the downloaded sample App and open it in your IDE.
Run npm install from the terminal in your IDE.

The generated project contains the Flowgear SDK, App manifest, icon, agent guidance, local HTTPS setup, and .env.local values for the selected Tenant, Site, and Environment.

Configure local development

Review .env.local in the project root. The downloaded sample App includes this configuration, but you can update it when you need to target different development values:

FG_DEV_TENANT=yourTenantKey
FG_DEV_SITE=yourSiteKey
FG_DEV_ENVIRONMENT=yourEnvironmentKey

yourTenantKey is the Tenant you use to sign in to the Console.
yourSiteKey is the Site that contains the backing Workflows.
yourEnvironmentKey is the Test Environment used during development.

Build with an agent

See Build an App with an agent for the complete cross-layer process. The short path is:

Register Builder MCP as flowgear in your AI agent.
Ask the agent to read the repository's agents.md and Builder Guidance before changing the project.
Describe the user outcome, required views, source systems, inputs, outputs, and operations that may change external data.
Ask the agent to build the smallest end-to-end feature first. It should create and Debug the required HTTP-bound Workflows, then bind the frontend through Flowgear.Sdk.invoke.
Review the generated frontend, Workflow YAML, Cookie-based Key scope, and test logs before expanding the feature.

Follow Build a Workflow with Builder MCP for the backend discovery, Debug, repair, and save loop.

Run the App locally

Run npm run dev from the project terminal.
Open the local App tab and accept its development-only certificate warning.
Switch to the Console debug tab and refresh it if the embedded App did not load before the certificate was trusted.
Exercise each Workflow-backed action against small Test Environment data.
Inspect the browser result and the corresponding Flowgear Workflow logs.

The debug URL carries the development Site and Environment into the Console. The App initializes the Flowgear SDK before rendering and synchronizes client-side navigation with the parent Console route.

Invoke Workflows from the frontend

Use Flowgear.Sdk.invoke(method, relativePath, payload?, headers?, tenant?). Use openapi.yml to discover the available method and relative route, but do not copy its server, component, or security sections into the call.

See App Console SDK for initialization, context, invocation, alerts, dialogs, URL opening, and route synchronization.

Do not call embedded Workflow endpoints directly with fetch or axios. The SDK asks the Console to invoke on behalf of the signed-in user, and a Cookie-based Key limits the permitted users and Workflows.

A standalone web app can call the same HTTP Workflows with a Token-based Key, but it does not receive the Console SDK context. See App security model before choosing this architecture.

Publish the App

When you have finished work on your App, package it so that others in your Flowgear Tenant can use it.

See App manifest and package for the authoritative fields, ZIP layout, update behavior, and validation errors.

Prepare public/app.json (manifest). Example:
```
{
  "Name": "SampleApp",
  "Version": "1.0.0.0",
  "DisplayName": "Sample App",
  "Rank": 1
}
```
- Name must be globally unique, for example your-company.your-app.
- Increment Version every publish.
- Rank controls the App's order in Console navigation.
Add public/icon.svg. This icon appears in Console navigation after the App is assigned to a Site.
Build:
```
npm run build
```
Zip the build directory contents (Vite output). The ZIP root must contain app.json, the landing page, icon.svg, and the generated asset folders; do not place them inside an extra build directory.
Open Settings → Manage Apps, click Publish App, select the owning Account, upload the ZIP, then click Submit.
Open the published App from the list, select a Site under Publish to Site, then click Publish.

Publishing a new App Version retains its existing Site assignments, but it does not publish or release backing Workflow changes. Verify the App package, Workflow revisions, API Keys, and Site assignments together before production rollout.