Skip to content

Getting Started

If you have never used Mozaiks before, start here.

The recommended first experience is:

  1. set your environment
  2. create a local workspace
  3. open Studio
  4. build your app through the factory_app workflows

You do not need to hand-author workflows, modules, or branding before you open Studio.

What Mozaiks Is Doing

There are three layers involved in the first-run experience:

  • mozaiks CLI
  • bootstraps a local workspace and launches the app
  • Studio
  • browser UI where you create and manage builds
  • factory_app
  • the shared build workflows that decompose intent and generate the app

Important:

  • the local workspace scaffold is not the finished app
  • the generated app is staged separately first
  • Studio and the generator workflows are the primary build path

Use the full Mozaiks repo checkout and launch Studio locally.

Why this is the recommended path:

  • Studio lives in the shared frontend shell
  • the builder workflows live in factory_app
  • those pieces are available in the repo checkout

If a public mozaiks release is not yet available on PyPI, use the full repo checkout path below. The repo-first path remains the most complete builder experience during active framework development.

Prerequisites

You need:

  • Python 3.11+
  • Node.js 18+
  • MongoDB, either:
  • local MongoDB, or
  • MongoDB Atlas
  • one supported LLM provider key, such as:
  • OPENAI_API_KEY
  • ANTHROPIC_API_KEY

Check your tools:

python --version
node --version

Step 1: Clone The Repo

git clone https://github.com/BlocUnited-LLC/mozaiks.git
cd mozaiks

Fastest Path

If you already cloned the repo and want the shortest supported path into Studio, run the bootstrap script from the repo root.

PowerShell

.\scripts\bootstrap-builder.ps1 -Workspace .\my-first-mozaiks-app

macOS / Linux

./scripts/bootstrap-builder.sh --workspace ./my-first-mozaiks-app

What this does:

  • creates .venv when missing
  • runs pip install -e .
  • launches mozaiks quickstart
  • opens Studio

If you want the manual steps instead, keep reading.

Step 2: Create A Virtual Environment

PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

macOS / Linux

python -m venv .venv
source .venv/bin/activate
pip install -e .

This installs the mozaiks CLI from your local repo checkout.

Important:

  • run the commands from the cloned mozaiks repo root
  • keep the virtual environment activated while you use mozaiks
  • this is the supported first-time setup path today

Choose Your Path

If you are new to Mozaiks, use the builder path.

  • Builder path
  • You want to build an app through Studio and the shared factory_app workflows.
  • Use mozaiks quickstart.
  • Framework path
  • You are working on the runtime, CLI, platform hosts, workflow generator, or repo internals.
  • Use mozaiks onboard --full, mozaiks studio, mozaiks init, and mozaiks serve directly.

Step 3: Set Your Environment Variables

Before launching Studio, set:

  • your LLM key
  • your Mongo connection string

PowerShell example

$env:OPENAI_API_KEY="sk-..."
$env:MONGO_URI="mongodb://localhost:27017/mozaiks"

Bash example

export OPENAI_API_KEY="sk-..."
export MONGO_URI="mongodb://localhost:27017/mozaiks"

If you use Anthropic instead of OpenAI:

$env:ANTHROPIC_API_KEY="sk-ant-..."

export ANTHROPIC_API_KEY="sk-ant-..."

If you prefer MongoDB Atlas, set MONGO_URI to your Atlas connection string.

Step 4: Quickstart Into Studio

Run:

mozaiks quickstart --dir ./my-first-mozaiks-app

What this does:

  • creates a workspace scaffold if it does not exist
  • writes minimal core app config files
  • launches the local backend
  • launches the frontend shell
  • opens Studio in your browser

If you want detailed branding/admin setup later, use:

mozaiks onboard --dir ./my-first-mozaiks-app --full

Step 5: Open Studio Create

If the browser did not open automatically, go to:

http://localhost:3000/studio/create

This is the main first-run entrypoint.

Step 6: Start Your First Build

In Studio Create:

  1. choose Greenfield App
  2. choose your validation strategy
  3. paste your build request
  4. start the build

Example prompt:

Build me a trading bot app that lets a user describe a trading strategy,
configure risk controls, backtest the strategy, and monitor live signals in a
clean dashboard.

At this point, the factory_app workflows take over.

The flow is:

  1. ValueEngine
  2. DesignDocs
  3. AgentGenerator
  4. AppGenerator

You are now using the canonical Mozaiks build path.

What Happens Behind The Scenes

Mozaiks does not immediately overwrite your workspace with generated files.

Instead:

  1. the workspace scaffold gives the host something to run
  2. the generator workflows create staged artifacts
  3. those artifacts are reviewed and then promoted explicitly

Generated output is staged under a path like:

generated/apps/{app_id}/{build_id}/app

That means:

  • your scaffold is the working shell
  • the generated app is a staged build artifact
  • promotion is a separate step

If you were expecting Mozaiks to directly fill app/workflows/ and app/modules/ in place during the build, that is not the intended lifecycle.

The Simplest Mental Model

If you are brand new, think about Mozaiks like this:

  • quickstart
  • prepares the local workspace and opens Studio
  • studio --open
  • advanced way to open the builder directly
  • factory_app
  • does the actual build planning and generation
  • generated/apps/...
  • holds the staged output

Daily Commands

Once your workspace exists, these are the main commands you will use:

Builder quickstart:

mozaiks quickstart --dir ./my-first-mozaiks-app

Create or configure a workspace with the lower-level setup command:

mozaiks onboard --dir ./my-first-mozaiks-app

Open Studio directly:

mozaiks studio --dir ./my-first-mozaiks-app --open

Inspect workspace status:

mozaiks studio --dir ./my-first-mozaiks-app --json

Use the advanced detailed onboarding flow:

mozaiks onboard --dir ./my-first-mozaiks-app --full

Troubleshooting

pip install mozaiks did not work

That is expected until the first public PyPI release is live.

Mozaiks' Studio-first builder flow depends on the full repo checkout, including:

  • factory_app/
  • web_shell/
  • the local CLI source

If you ran:

pip install mozaiks

and then:

mozaiks --version

that does not currently represent the supported setup path unless you are installing from an official published release. Use:

git clone https://github.com/BlocUnited-LLC/mozaiks.git
cd mozaiks
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
mozaiks --version

If mozaiks is still not recognized, make sure your virtual environment is activated and run the module entrypoint directly:

python -m mozaiks_cli.main --version

If you already had an older local install cached, remove it before retrying:

python -m pip uninstall mozaiks

Studio does not open

Check:

  • backend: http://localhost:8000/api/health
  • frontend: http://localhost:3000

If the frontend is not running, make sure:

  • Node.js is installed
  • web_shell dependencies can install successfully

Mongo connection errors

Make sure:

  • MongoDB is running locally, or
  • your Atlas URI is correct in MONGO_URI

LLM key errors

Make sure you exported the provider key that matches the model/provider you selected during onboarding.

Examples:

  • OPENAI_API_KEY
  • ANTHROPIC_API_KEY

Port already in use

Use different ports:

mozaiks studio --dir ./my-first-mozaiks-app --open --backend-port 8001 --frontend-port 3001

Advanced: Runtime-Only Path

If you are not trying to use Studio and only want the runtime/CLI surfaces, you can still use the lower-level path:

mozaiks init chat --name my-app --dir ./my-app
mozaiks serve ./my-app --host platform

But for a first-time user who wants to build apps with the generator, the recommended path is:

.\scripts\bootstrap-builder.ps1 -Workspace .\my-first-mozaiks-app

./scripts/bootstrap-builder.sh --workspace ./my-first-mozaiks-app