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. For most readers, the easiest place to do that is from an IDE or editor, where you can also use the Builder MCP Server to create Flowgear Workflows agentically. If your coding agent also supports terminal-first or standalone graphical use, those are valid options as well.

Steps

In the Console, go to Settings → Manage Apps, then click Download a sample App.
Extract the downloaded sample app and open it in your IDE (try Visual Studio Code if you're just getting started).
Run npm install from the terminal in your IDE.
Review the .env.local file in the project root. The downloaded sample app includes this configuration, but you can update it if you need to target different values:
```
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.
Register the Flowgear Builder MCP Server in your AI agent. For most readers, this will be from the project opened in your IDE.
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.
Run the app using npm run dev from the terminal. As long as you've configured the .env.local file, two browser tabs will open. The first opens the raw app and may present an untrusted certificate warning because the certificate is a development-only certificate. Accept the certificate, then switch to the second tab that opened and refresh the page to see the app embedded into the Console.

More about how Apps work

Flowgear Apps embed directly into 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.

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.
Add public/icon.svg (menu + focus icon). This icon will be shown in the left-hand menu once your app is published.
Build:
```
npm run build
```
Zip the dist directory contents (Vite output).
In Flowgear: Settings, Manage Apps, + Publish App, pick the account, upload the ZIP, and Submit.
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, selecting a site from Publish to Site, and then Publish.