Skip to content

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.

Prerequisites

  • Python 3.11+
  • Node.js 18+
  • MongoDB locally or MongoDB Atlas
  • one LLM provider key, usually OPENAI_API_KEY or ANTHROPIC_API_KEY

Check local tools:

python --version
node --version

Source Checkout Bootstrap

Use this path when you are changing Mozaiks itself:

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

On macOS or Linux:

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

The bootstrap script creates .venv when needed, installs the local package in editable mode, starts the builder stack, and opens the Mozaiks Console.

Manual Editable Setup

Use this only when you need to run each step yourself:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
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"

Use Anthropic instead of OpenAI if preferred:

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

Start the local builder:

mozaiks quickstart --dir .\mozaiks-workspace

Open:

http://localhost:3000/apps

Useful Commands

mozaiks quickstart --dir .\mozaiks-workspace
mozaiks studio --dir .\mozaiks-workspace --open
mozaiks studio --dir .\mozaiks-workspace --json
mozaiks onboard --dir .\mozaiks-workspace --full

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 (opens a backend terminal + runs frontend here):

.\scripts\run-studio.ps1

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 Console stack.

Runtime-Only Path

If you only want the app runtime and not the Console-driven builder:

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

Most new users should use the Console path instead.

Generated Output

Mozaiks stages generated output before it touches an active app workspace:

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

Promotion is the explicit step that moves validated artifacts into an active app root.

Troubleshooting

Console does not open

Check:

  • backend health: http://localhost:8000/api/health
  • frontend shell: http://localhost:3000
  • Node 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

Set the provider key matching the model/provider you selected:

  • OPENAI_API_KEY
  • ANTHROPIC_API_KEY

Port already in use

Use a different backend/frontend port:

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

Or stop the existing local process before restarting.