Skip to content
Core-X Docs

Quickstart

Prerequisites

Terminal window
# Homebrew basics
brew install python@3.12 node ffmpeg


# Verify
python3 --version   # 3.12 required (core-x/corex-cli-v2 declare >=3.10,
                     # but corex-disk-study requires >=3.12 — use 3.12 everywhere)
node --version      # >= 18
ffmpeg -version     # required for audio/video pipelines

First-Run Checklist

Before launching anything for the first time:

  1. Brew deps — brew install python@3.12 node ffmpeg (see versions above)
  2. Node deps — cd core-x/ui && npm install
  3. Ports free — Verify nothing is squatting on 5200, 5201, 8085, 8090–8096 (lsof -i :8090)
  4. Disk budget — MLX models can be 4–20 GB each; ensure ~50 GB free for standard tier
  5. Models downloaded — Models are fetched on first service start; initial launch will be slow

A) Minimal — Gateway Only

Terminal window
cd ~/core-x-kbllr_0
cd mlx-services && ./start-all.sh --only gateway

Verify:

Terminal window
curl http://localhost:8090/health
# Expected: {"status":"ok"} or similar JSON

B) Core Tier (gateway + llm + rag)

Terminal window
cd ~/core-x-kbllr_0/mlx-services
./start-all.sh --profile minimal

Verify:

Terminal window
curl http://localhost:8090/health   # gateway
curl http://localhost:8091/health   # mlx-llm
curl http://localhost:8092/health   # mlx-rag

C) Standard Tier (core + audio + embed + mflux)

Terminal window
cd ~/core-x-kbllr_0/mlx-services
./start-all.sh --profile standard

Verify:

Terminal window
curl http://localhost:8093/health   # mlx-audio
curl http://localhost:8095/health   # mlx-embed
curl http://localhost:8083/health   # mflux

D) Full Tier (all services)

Use the main launcher, which orchestrates everything including event bus and UI:

Terminal window
cd ~/core-x-kbllr_0
./launch-core-x.sh                      # Standard + voice/avatar
./launch-core-x.sh --with-image-lane    # Full tier (adds mflux + vision)
./launch-core-x.sh --no-mlx             # Skip MLX services (if already running)
./launch-core-x.sh --stop               # Stop all services
./launch-core-x.sh --status             # Show service status

Launcher contract — actual output of ./launch-core-x.sh --help:

Usage: ./launch-core-x.sh [OPTIONS]


Options:
  --no-mlx    Skip starting MLX services (if already running)
  --with-image-lane  Also start mflux + mlx-vision for image workflows
  --stop      Stop all services
  --status    Show service status
  --help      Show this help

The launcher sequence:

  1. Starts MLX services via mlx-services/start-all.sh
  2. Starts Event Bus on :8085
  3. Starts Observability API on :5201
  4. Starts UI dev server on :5200
  5. Health-checks each service with retries (up to 90s for MLX, 15s for UI)

Verify full stack:

Terminal window
for port in 8090 8091 8092 8085 8093 8096; do
  echo -n "Port $port: "
  curl -s http://localhost:$port/health | head -c 60
  echo
done