Building Apps

Build web apps that embed directly into the Flowgear Console to create rich user experiences.

We recommend using an AI agent to help you build where you'll also be able to use the Builder MCP Server to create Flowgear workflows directly in your IDE.

Steps

1. Clone the sample GitHub repo at https://github.com/Flowgear/flowgear-sample-app.

2. Run npm install from the terminal in your IDE (try Visual Studio Code if you're just getting started).

3. Update the .env.local file in the project root with:

   FG_DEV_TENANT=yourTenantKey
   FG_DEV_SITE=yourSiteKey
   FG_DEV_ENVIRONMENT=yourEnvironmentKey
   

   • yourTenantKey is the one you use to sign in to the Console.
   • yourSiteKey is the key of the Site you're going to create backing Workflows in. You can obtain it from the URL when you're signed in to the Console or from the Site Detail Pane.
   • yourEnvironmentKey is the Environment you're going to target while developing the app. We recommend using the first (test) Environment and you can find its key under Environments on the Site Detail Pane.

4. Register the Flowgear Builder MCP Server in your AI agent in your IDE.

5. Ask the agent to build a feature, it will be directed via the agents.md file on how to create the required set of backing HTTP-bound workflows

6. Run the app using npm run dev from the terminal. As long as you've configured the .env.local file, a browser tab will open directly to the Console where the app you're building will embed directly for debugging.

More about how apps work

Flowgear Apps embed directly in to the Console, inheriting the context of the current user.

Workflows that are built agentically, will be created as HTTP-bound Workflows but they are authorized via Cookie-based Keys. This enables the Flowgear Console to provide the security context that controls which Workflows the user is able to invoke.

You can also build apps that run outside of Flowgear. To use Workflows in this mode, use a Token-based Key.

Publishing your app

When you have finished work on your app, you can package it so that others in your Flowgear tenant are able to use it.

1. Prepare public/app.json (manifest). Example:

   {
     "Name": "SampleApp",
     "Version": "1.0.0.0",
     "DisplayName": "Sample App",
     "Rank": 1
   }
   

   • Name must be globally unique (e.g., your-company.your-app).
   • Increment Version every publish.
   • Rank controls embed order within the console.
2. Add public/icon.svg (menu + focus icon).
3. Build:

   npm run build
   

4. Zip the dist directory contents (Vite output).
5. In Flowgear: Settings, Manage Apps, + Publish App, pick the account, upload the ZIP, Submit.
6. After publish, the new app will be listed. You can choose which Sites the app will display under by clicking into it from the list and then selecting a site from Publish to Site, then Publish.

The app icon will be shown in the left-hand menu.