Skip to main content
Version: 2.0-dev

Getting Started

MaestroHub helps industrial teams connect disparate systems, model operations, and orchestrate real-time data pipelines. Use this guide to work through the practical setup steps: confirm prerequisites, install the platform, bring the MaestroHub UI online, and finish configuration with the in-app onboarding tour.

Begin with installation, then sign in to the MaestroHUB UI, and finally let the interactive onboarding guide you through building your first flow.

MaestroHub Lite​

MaestroHub Lite is a single executable that bundles and runs all MaestroHub services with zero configuration required.

MaestroHub Lite is currently available as a beta release for Windows, macOS, and Linux. As this is a beta version, we appreciate your understanding and patience as we continue to develop and improve the platform.

Windows Installation​

  1. Download the MaestroHub Lite ZIP file for Windows.
  2. Extract the ZIP file to a folder of your choice.

After extraction, you'll see the following structure:

maestrohub-lite/
├── README.txt
├── ThirdPartyNotices.txt
├── starter.bat
├── maestrohub-lite.exe
└── config.yaml
  1. Double-click starter.bat to start the application. If your system blocks .bat files for security reasons, you can run maestrohub-lite.exe directly instead.

A console window will appear showing the application starting all services. Once all services are running, your default browser will automatically open to http://localhost:6163 where you can sign in and start using MaestroHub.

macOS Installation​

  1. Download the MaestroHub Lite archive for your Mac:
    • Apple Silicon (M1/M2/M3): maestrohub-lite_*_darwin_arm64.tar.gz
  2. Extract the archive: 
    tar -xzf maestrohub-lite_*_darwin_*.tar.gz

After extraction, you'll see the following structure:

maestrohub-lite/
├── README.txt
├── ThirdPartyNotices.txt
├── maestrohub-lite
└── config.yaml
  1. Run the application by double-clicking maestrohub-lite or run this command in Terminal: 
    ./maestrohub-lite

The application will start all services and automatically open the web UI in your default browser at http://localhost:6163.

macOS Security Settings

If macOS blocks the application with a message that it "cannot be opened because it is from an unidentified developer," you need to allow it in your security settings:

  1. Go to System Settings (or System Preferences on older macOS) > Privacy & Security
  2. Scroll down to the Security section
  3. You'll see a message that MaestroHub Lite was blocked
  4. Click Open Anyway and confirm

For more information, see Apple's guide on opening apps from unidentified developers.

Linux Installation​

  1. Download the MaestroHub Lite archive: maestrohub-lite_*_linux_amd64.tar.gz
  2. Extract the archive: 
    tar -xzf maestrohub-lite_*_linux_amd64.tar.gz

After extraction, you'll see the following structure:

maestrohub-lite/
├── README.txt
├── ThirdPartyNotices.txt
├── maestrohub-lite
└── config.yaml
  1. Run the application: 
    ./maestrohub-lite

The application will start all services and automatically open the web UI in your default browser at http://localhost:6163.

Running and Managing​

Once you run MaestroHub Lite, it will:

  • Start all MaestroHub services automatically
  • Open the web UI at http://localhost:6163 in your default browser
  • Application data files are stored in ~/maestrohub/data/ (under your home directory)
  • Configuration is stored in config.yaml alongside the executable

Configuration​

You can customize MaestroHub by editing the config.yaml file. For example, to change the server port:

http:
  port: 8080

Alternatively, you can use environment variables with the MAESTROHUB_ prefix:

export MAESTROHUB_HTTP_PORT=8080

After making changes, restart the application for them to take effect.

Shutting Down​

To shut down MaestroHub, press Ctrl+C (or Cmd+C on macOS) in the terminal to initiate a graceful shutdown.

Troubleshooting​

  • Verify the application is running by checking the console window
  • Review application logs stored in ~/maestrohub/data/ within your home directory
  • Ensure port 6163 is not already in use and is not blocked by your firewall or antivirus software such as Windows Defender
  • If you want to restart the application with a data purge, you can clear the data directory ~/maestrohub/data/

Build Your First Pipeline​

When MaestroHub is running, the application automatically opens the UI in your browser at http://localhost:6163.

When you start MaestroHub Lite for the first time, you'll need to create an initial administrator account. After creating the initial account, you will be signed in automatically and redirected to the home page.

Create admin account form

Create your initial administrator account to get started with MaestroHub.

Once you're signed in, the interactive onboarding immediately begins, spotlighting each screen you need to configure. The guided tour walks you through building your first working data flow step-by-step, so you know exactly which fields to fill and where to click next.

Interactive onboarding overlay in MaestroHub

Onboarding overlays guide you through every configuration step inside the MaestroHub UI.

The tour is organized into guided checkpoints, each with inline tooltips and prompts that explain exactly what to enter before you can continue:

  1. Create Connection - learn how to connect to external REST APIs, configure authentication and base URLs, and test integrations before saving.
  2. Create Function - recap what you just learned by defining API endpoints, selecting HTTP methods, validating responses, and turning them into reusable calls.
  3. Create Data Model - reinforce consistent schemas by choosing field names, types, and validation rules that keep structures aligned.
  4. Create Function Instance - combine functions with data models to produce reusable pipeline components while validating data shapes.
  5. Build & Execute Pipeline - explore the visual designer, connect nodes into end-to-end workflows, fine-tune transformation logic, and run the pipeline while reviewing executions in the history view.

Every checkpoint validates the data you submit, highlights the UI elements to touch next, and provides a "Continue" cue that moves you forward only when the step is complete. Stick with the tour before exploring advanced screens to ensure every dependency is configured correctly.

Core capabilities to explore next​

Data Integration

Connect PLCs, historians, and IT systems while orchestrating flows with the visual pipeline designer.

Explore the guide

Unified Namespace

Distribute real-time and historical data across teams with an UNS backbone and event-first architecture.

Explore the guide

Operations & Diagnostics

Monitor pipelines, system health, and connector activity with built-in dashboards and alerting hooks.

Explore the guide