Docs

Setup Wizard

What this screen is for

The Setup Wizard defines the steps someone must run locally before the application will work on their machine: cloning repositories, adding hosts entries, running init scripts, or supplying environment-specific values.

It is not part of the deployment. It is the README you would otherwise write and nobody would follow.

Before you start

To do this You need
Open App Builder the App Builder access permission

Opening it

The Setup Wizard tab in the tab bar.

The Setup Wizard tab lets you configure a guided setup experience for developers who will run your application locally using the Fenwave Agent CLI. It standardizes local development environment setup across your team.

📸 Screenshot Placeholder: The Setup Wizard tab with one task defined. Mark: (1) the enable control, (2) the Allow Skip setting, (3) a task and its type, (4) the variables section.

Overview

Use the Setup Wizard when your application requires specific local setup steps — cloning repos, adding hosts entries, running init scripts, or collecting environment-specific values.

Access it by clicking the “Setup Wizard” tab in the tab bar.

Enabling the Wizard

Toggle “Enable Local Setup Wizard for this application” to ON. The wizard runs automatically when the app is first set up locally.

Setup Notes

Provide instructions or prerequisites that developers see before starting the wizard (e.g., required tools, available ports, credentials to have ready).

Allow Skip

Toggle whether developers can skip the entire wizard. Enable for experienced users or simple setups; disable when specific steps are mandatory.

Setup Tasks

Tasks are the individual steps developers execute during the wizard. They run in order from top to bottom.

Available Task Types

Task Type Purpose Example
Git Clone Clone a repository to a specified location Clone application source code
Hosts Entry Add entries to the system hosts file Map api.local to 127.0.0.1
File Copy Copy or create a file (supports templates) Copy .env.example to .env
File Edit Edit an existing file Modify configuration files
Command Execute a shell command Run npm install
Input Prompt the user for input, store as a variable Collect API keys
Checkbox Confirm a manual step is completed Confirm database setup
Path Select Select a directory path Choose project directory
SSL Certificate Generate local SSL certificates using mkcert Create certs for local HTTPS

Task Configuration

All tasks share a Title (required) and Description (optional). Type-specific fields:

Git Clone: Repository URL (required), Branch (optional)

Hosts Entry: Hostname (required), IP Address (optional, defaults to 127.0.0.1)

File Copy: Source Path, Destination Path (required), Template Content (supports `` substitution)

File Edit: Source Path (required), Destination Path (required)

Command: Command (required), Working Directory (optional)

Input: Input Label (required), Placeholder, Validation Pattern (regex)

Checkbox: Checkbox Label (required)

Path Select: Path Label (required), Must Contain (comma-separated list of files that must exist)

SSL Certificate: Domains (required, comma-separated), Cert Name (optional), Install CA (default: true). Requires mkcert to be installed. Generates three output variables: ,, ``.

Managing Tasks

  • Reorder: Use the up/down arrows on each task row
  • Edit: Click the edit icon to modify, then save
  • Delete: Click the delete icon to remove

Variables

Tasks can define and consume variables to pass data between steps.

Defining Variables

Set an Output Variable name on any task. When the wizard runs, the task’s result is stored in that variable:

  • Input tasks → user’s input value
  • Git Clone tasks → cloned repository path
  • Path Select tasks → selected directory path
  • SSL Certificate tasks → three paths (cert, key, CA)

Using Variables

Reference variables in subsequent tasks with ``:

git clone https://@github.com/org/repo.git

The Setup Wizard panel shows an “Available Variables” section listing all defined variables.

Validation

Variables must be defined by a task that runs before the task using them. Undefined references trigger a warning showing which task and variable are affected.

Best Practices

Recommended task order:

  1. Checkbox — Confirm prerequisites (e.g., Docker installed)
  2. Input — Collect credentials/tokens
  3. Git Clone — Get source code
  4. File Copy — Set up configuration files
  5. Hosts Entry — Configure local hostnames
  6. SSL Certificate — Generate certificates (if needed)
  7. Command — Install dependencies and initialize

Scenario

New joiners keep failing at the same local step.

  1. Find the step that trips people. It is usually a hosts entry or a script that the original author has long since forgotten they ran.
  2. Open the Setup Wizard tab and enable it.
  3. Add that step as a task of the right type, with a clear description. The description is read by someone who does not yet know what the application does — write for them, not for you.
  4. Where the step needs a value that differs per person, define a variable rather than hardcoding your own. Add validation so a wrong value is caught at entry rather than three steps later.
  5. Decide on Allow Skip deliberately. A skippable required step gets skipped.
  6. Have the next new joiner run it and watch without helping. Every place they hesitate is a description that needs work.

When it doesn’t work

Symptom Cause How to check Fix
The wizard does not appear for users It is not enabled The Setup Wizard tab Enable it
A variable is not substituted The reference does not match the definition The variable name Names must match exactly
Users skip a required step Allow Skip is on The Allow Skip setting Turn it off for genuinely required steps
A task fails silently Its type does not match what it does The task type Pick the type matching the action

Next