Local Setup¶

Use this page when Getting Started is not enough and you need to debug a local run or work from a repo checkout.

If you only want to create your first app, start with Getting Started instead.

Choose The Right Setup Path¶

Use one setup path at a time:

Do not create a shared .venv in the parent folder that contains multiple repos. Put the environment in the repo or workspace that owns it. For the public package path, install Mozaiks into the Python environment you normally use for command-line tools. Mozaiks is not on PyPI yet, so that means python -m pip install -e <path-to-mozaiks> from a clone.

Studio requires MongoDB at startup. Docker Desktop is not required when you use MongoDB Atlas or a native local MongoDB server, but the repo convenience scripts start Docker Compose infra by default. If you already have MongoDB available, set MONGO_URI and launch repo scripts with -SkipInfra.

Prerequisites¶

• Python 3.11+
• Node.js 20.19+ or 22.12+ (required by the Vite 8 frontend toolchain)
• MongoDB Atlas or a local MongoDB server
• an OpenAI API key (OPENAI_API_KEY); builds call OpenAI only today

Tree-sitter parser packages are installed with Mozaiks itself. They are the baseline parser path for source-backed App Intelligence; deterministic fallbacks only cover parser-package failures.

FalkorDB is recommended for production or team-scale App Intelligence querying and Studio visualization. Local setup can use artifact-backed snapshots until you need a shared graph service.

Check local tools:

python --version
node --version

python --version
node --version

Source Checkout Bootstrap¶

Use this path when you are changing Mozaiks itself. The bootstrap script creates .venv inside the cloned mozaiks/ repo:

git clone https://github.com/BlocUnited-LLC/mozaiks.git
cd mozaiks
.\scripts\bootstrap-builder.ps1 -Workspace .\mozaiks-workspace

It installs the local package in editable mode, starts the local Mozaiks services, and opens Studio.

Manual Editable Setup¶

Use this only when you need to run each step yourself from a cloned mozaiks/ repo:

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

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

Set the minimum required environment:

$env:OPENAI_API_KEY="sk-..."
$env:MONGO_URI="mongodb://localhost:27017/mozaiks"
$env:AUTH_ENABLED="false"
$env:AUTH_ANON_ROLES="admin,user"

export OPENAI_API_KEY="sk-..."
export MONGO_URI="mongodb://localhost:27017/mozaiks"
export AUTH_ENABLED="false"
export AUTH_ANON_ROLES="admin,user"

Builds call OpenAI only today. The default model is gpt-5-nano; set DEFAULT_LLM_MODEL to use another OpenAI model. The two AUTH_ settings run Studio without sign-in for requests from this machine and give the anonymous user the admin role. With no auth setting at all, the backend refuses to start and names the settings to choose from.

If the repo also has a .env, the backend script loads it too; values set in the shell win. A .env copied from .env.example sets DEFAULT_LLM_MODEL=gemini-2.0-flash, and the runtime would send that model name to OpenAI, so change it to an OpenAI model such as gpt-5-nano.

Install the frontend dependencies once, from the repo root (the same commands in every shell):

npm --prefix chat-ui install
npm --prefix web_shell install

Start the repo development Studio from Windows PowerShell:

.\scripts\run-studio.ps1

The script opens the backend in a separate terminal, waits for http://localhost:8000/api/shell-config, then starts the Vite frontend in the current terminal.

If Docker Desktop is not running because you are using MongoDB another way:

.\scripts\run-studio.ps1 -SkipInfra

Open:

http://localhost:3000/apps

After Studio starts, run the local smoke from the repo root in a new terminal:

.\scripts\smoke-studio-local.ps1

For a fast HTTP-only check without opening the browser smoke:

.\scripts\smoke-studio-local.ps1 -SkipBrowser

Which Tool To Use Here¶

Use the CLI for local-machine tasks:

• create the local workspace when it does not exist yet
• start or reopen the backend/frontend processes
• inspect status or run diagnostics

Use Studio for product tasks:

• create apps
• continue builds
• review staged artifacts
• open app-specific pages and tools

The CLI gets the local install running. Studio is where you actually use Mozaiks after that. See the CLI Reference for all commands.

Useful Commands¶

python -m mozaiks quickstart --dir .\mozaiks-workspace
python -m mozaiks studio --dir .\mozaiks-workspace --open
python -m mozaiks studio --dir .\mozaiks-workspace --json
python -m mozaiks onboard --dir .\mozaiks-workspace

python -m mozaiks quickstart --dir ./mozaiks-workspace
python -m mozaiks studio --dir ./mozaiks-workspace --open
python -m mozaiks studio --dir ./mozaiks-workspace --json
python -m mozaiks onboard --dir ./mozaiks-workspace

quickstart is the preferred local command. The lower-level studio command is mainly useful when you need explicit ports, JSON status output, or process debugging.

Repo Dev Scripts¶

The repo scripts are for framework development from a source checkout. They are not the public package install path.

Single-command start from Windows PowerShell. This opens the backend in a new terminal, waits for the backend shell config endpoint, then runs the frontend in the current terminal:

.\scripts\run-studio.ps1

For a clean testing restart, use:

.\scripts\run-studio.ps1 -ForceStop

That stops existing backend/frontend listeners and clears prior files under logs/logs/, logs/agent_outputs/, and logs/workflow_converter/ before the new Studio run starts.

If MongoDB is already running outside Docker, use:

.\scripts\run-studio.ps1 -SkipInfra

Or start each service manually in separate terminals:

Terminal 1 — backend:

.\.venv\Scripts\Activate.ps1
.\scripts\run-backend.ps1 -ForceStop

Terminal 2 — frontend:

.\scripts\run-frontend.ps1 -ForceStop

These scripts use the repo-local factory_app/app, factory_app/workflows, and web_shell/ sources. The backend script can start local Docker Compose infra for Mongo and Keycloak. Use them when you are changing Mozaiks itself or debugging the Studio stack.

For the boundary between repo-local infra/, the first-party factory_app/ workspace, and generated app deployment artifacts, see docs/architecture/deployment/oss-infra-and-generated-app-deployment.md.

Runtime-Only Path¶

If you only want the app runtime and not the Studio setup flow:

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

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

Most new users should use the Studio path instead.

Generated Output¶

Mozaiks writes generated output here before it is copied into an app:

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

Promotion is the explicit step that copies approved generated files into the app.

Troubleshooting¶

Studio does not open¶

Check:

• backend health: http://localhost:8000/health
• backend shell config: http://localhost:8000/api/shell-config
• frontend shell: http://localhost:3000/apps
• Node dependencies under web_shell/
• local smoke: .\scripts\smoke-studio-local.ps1 -SkipBrowser

If startup stops before the frontend launches, check the backend terminal first. Common causes are Docker Desktop not running, MongoDB not reachable, missing Python dependencies, or missing frontend dependencies under web_shell/.

Mongo connection errors¶

Confirm local MongoDB is running or MONGO_URI points to a valid Atlas connection string.

LLM key errors¶

Builds call OpenAI only today, whatever provider is configured elsewhere. Set OPENAI_API_KEY, and make sure DEFAULT_LLM_MODEL, when set, names an OpenAI model (the default is gpt-5-nano). Gemini and Anthropic keys are not used for builds yet.

If the backend log says GEMINI_API_KEY / GOOGLE_API_KEY / LLM_PRIMARY_API_KEY is not set, the environment has LLM_PRIMARY_API_TYPE=google (the .env.example value). That setting changes only the startup check and the Studio integrations summary; set it to openai so both report the key builds actually use.

Port already in use¶

python -m mozaiks studio --dir .\mozaiks-workspace --open --backend-port 8001 --frontend-port 3001

python -m mozaiks studio --dir ./mozaiks-workspace --open --backend-port 8001 --frontend-port 3001

Or stop the existing local process before restarting.