Install and run

Get started takes the shortest way in. This page has every way to install MaestroHub, and what you may need once it runs.

Install

MaestroHub runs as a single binary or Docker container. No external databases, no message brokers: everything is embedded.

Binary (Recommended)

Download from the MaestroHub Portal and run:

Windows

1. Download the ZIP file and extract it

After extraction, you'll see the following structure:

context-platform_3.0.0_windows_amd64/
├── README.txt
├── ThirdPartyNotices.txt
├── starter.bat
├── context-platform.exe
├── admin-cli.exe
└── config.yaml

2. Double-click starter.bat (or run context-platform.exe directly)

macOS

tar -xzf context-platform_*_darwin_arm64.tar.gz
cd context-platform_*_darwin_arm64
./context-platform

After extraction, you'll see the following structure:

context-platform_3.0.0_darwin_arm64/
├── README.txt
├── ThirdPartyNotices.txt
├── context-platform
├── admin-cli
└── config.yaml

macOS Security Settings

If macOS blocks the app 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 Context Engine was blocked
4. Click Open Anyway and confirm

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

Linux (AMD64)

tar -xzf context-platform_*_linux_amd64.tar.gz
cd context-platform_*_linux_amd64
./context-platform

After extraction, you'll see the following structure:

context-platform_3.0.0_linux_amd64/
├── README.txt
├── ThirdPartyNotices.txt
├── context-platform
├── admin-cli
└── config.yaml

Linux (ARM64)

tar -xzf context-platform_*_linux_arm64.tar.gz
cd context-platform_*_linux_arm64
./context-platform

After extraction, you'll see the following structure:

context-platform_3.0.0_linux_arm64/
├── README.txt
├── ThirdPartyNotices.txt
├── context-platform
├── admin-cli
└── config.yaml

ARM64

For Raspberry Pi 4/5, AWS Graviton, Ampere, or Apple Silicon running Linux.

The browser opens automatically at http://localhost:6163.

Docker

Download the Docker image for your architecture from the MaestroHub Portal.

AMD64 (Intel/AMD)

# Extract the zip
unzip context-platform_3.0.0_docker_amd64.zip

# Load the image
docker load -i context-platform-amd/context-platform-amd64.tar.gz

# Create persistent volume
docker volume create maestrohub-data

# Run
docker run -d \
  --name maestrohub \
  -p 8080:8080 \
  -p 1883:1883 \
  -p 8083:8083 \
  -v maestrohub-data:/data \
  maestrohub/context-platform:3.0.0

ARM64 (Apple Silicon)

# Extract the zip
unzip context-platform_3.0.0_docker_arm64.zip

# Load the image
docker load -i context-platform-arm/context-platform-arm64.tar.gz

# Create persistent volume
docker volume create maestrohub-data

# Run
docker run -d \
  --name maestrohub \
  -p 8080:8080 \
  -p 1883:1883 \
  -p 8083:8083 \
  -v maestrohub-data:/data \
  maestrohub/context-platform:3.0.0

Open http://localhost:8080 in your browser.

Windows Users

All commands above are written for Bash. Choose your preferred shell:

• Git Bash (Git for Windows): run commands as-is
• PowerShell: replace \ with ` (backtick) and $(pwd) with ${PWD}

Or use the Docker Compose tab for a shell-agnostic alternative.

Port	Description
8080	Web UI + REST API
1883	MQTT broker
8083	MQTT over WebSocket

Docker Compose

First, load the image (if not already loaded):

# AMD64 (Intel/AMD)
unzip context-platform_3.0.0_docker_amd64.zip
docker load -i context-platform-amd/context-platform-amd64.tar.gz

# Or ARM64 (Apple Silicon)
unzip context-platform_3.0.0_docker_arm64.zip
docker load -i context-platform-arm/context-platform-arm64.tar.gz

Save the following as docker-compose.yml:

services:
  maestrohub:
    image: maestrohub/context-platform:3.0.0
    container_name: maestrohub
    restart: unless-stopped
    ports:
      - "8080:8080"   # Web UI + REST API
      - "1883:1883"   # MQTT broker
      - "8083:8083"   # MQTT over WebSocket
    volumes:
      - maestrohub-data:/data
    # environment:
    #   - TZ=Europe/Istanbul

volumes:
  maestrohub-data:

Then run:

docker-compose up -d

Open http://localhost:8080 in your browser.

Works identically on Bash, PowerShell, and Cmd, with no shell syntax differences.

Port	Description
8080	Web UI + REST API
1883	MQTT broker
8083	MQTT over WebSocket

Configuration

Customize MaestroHub by editing config.yaml:

http:
  port: 8080

Or use environment variables with the MAESTROHUB_ prefix:

export MAESTROHUB_HTTP_PORT=8080

Restart the application after changes.

Docker lifecycle commands

# View logs
docker logs -f maestrohub        # or: docker-compose logs -f

# Stop (data preserved)
docker stop maestrohub            # or: docker-compose stop

# Start again
docker start maestrohub           # or: docker-compose start

# Health check
curl http://localhost:8080/health

# Full reset
docker stop maestrohub && docker rm maestrohub
docker volume rm maestrohub-data

Troubleshooting

• Port in use: Check lsof -i :6163 (binary) or lsof -i :8080 (Docker)
• macOS security block: System Settings > Privacy & Security > Open Anyway
• Clean restart: Delete ~/maestrohub/data/ (binary) or remove Docker volume
• Container not starting: Check docker logs maestrohub

Encryption keys and runtime secrets

MaestroHub uses several runtime secrets: JWT signing keys, the OAuth2 client secret, and encryption keys for the Connectors and UNS databases. They are persisted under a secrets/ subfolder of your MaestroHub data directory (mode 0600):

secrets/
├── auth_jwt_access_secret
├── auth_jwt_refresh_secret
├── auth_jwt_password_reset_secret
├── oauth2_secret
├── connectors_encryption_key
└── uns_encryption_key

Install	Where the secrets/ folder lives
Binary	~/maestrohub/data/secrets/ (i.e. inside $HOME/maestrohub/data/, alongside the SQLite database files)
Docker	inside the volume you mounted at /data (full path /data/data/secrets/ from inside the container)

Once a file exists in this directory, MaestroHub uses its contents as-is: keys never silently rotate underneath the data they protect.

Bring your own keys. Two ways, in order of precedence:

1. Environment variables. Set the value before the first boot (or before you next restart). Useful for Docker / orchestrators.

   Variable	Purpose
   MAESTROHUB_MODULES_AUTH_JWT_ACCESSSECRET	JWT access-token signing key
   MAESTROHUB_MODULES_AUTH_JWT_REFRESHSECRET	JWT refresh-token signing key
   MAESTROHUB_MODULES_AUTH_JWT_PASSWORDRESETSECRET	Password-reset token signing key
   MAESTROHUB_MODULES_OAUTH2_SECRET	OAuth2 client secret
   MAESTROHUB_MODULES_CONNECTORS_ENCRYPTIONKEY	AES key for connector secrets
   MAESTROHUB_MODULES_UNS_ENCRYPTIONKEY	AES key for UNS settings secrets

2. Pre-seed the secrets file. Write your value to data/secrets/<file> (mode 0600) before first boot. The runtime sees the file and uses it as-is.

Connector and UNS encryption keys must be 16, 24, or 32 bytes (AES-128 / 192 / 256). They can be supplied as raw bytes (ASCII) or as a base64-encoded string.

Rotating an encryption key. To rotate the Connectors or UNS encryption key against existing data, use admin-cli reencrypt. It re-wraps every encrypted row under the new key and updates the secrets file atomically.