Quickstart

This guide follows the current repo layout and route contracts.

Prerequisites

• Node.js 18+

• Python 3.10+

• Docker and Docker Compose

1. Install dependencies

git clone https://github.com/fortunexbt/mutx.dev.git
cd mutx.dev

npm install
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e ".[dev]"
cp .env.example .env

Set a local database URL in .env:

DATABASE_URL=postgresql://mutx:mutx_password@localhost:5432/mutx

2. Start local services

docker compose -f infrastructure/docker/docker-compose.yml up -d postgres redis

3. Start the API

uvicorn src.api.main:app --reload --port 8000

4. Start the web app

In another terminal:

npm run dev

Visit:

• http://localhost:3000 for the marketing site

• http://localhost:3000/app for the app-facing surface

5. Verify health

curl http://localhost:8000/
curl http://localhost:8000/health
curl http://localhost:8000/ready

6. Create a local user

curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"You","password":"StrongPass1!"}'

Log in and save the access token if you want to use /auth/me:

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"StrongPass1!"}'

7. Create and deploy an agent record

Log in first so you have an access token:

curl http://localhost:8000/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create the agent:

curl -X POST http://localhost:8000/agents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"My First Agent",
    "description":"Local test agent",
    "config":"{\"model\":\"gpt-4\"}"
  }'

Deploy it:

curl -X POST http://localhost:8000/agents/YOUR_AGENT_ID/deploy

Inspect the deployment:

curl http://localhost:8000/deployments
curl http://localhost:8000/agents/YOUR_AGENT_ID

Optional: CLI setup

The CLI installs from the repo root:

source .venv/bin/activate
pip install -e .
mutx status
mutx login --email [email protected]
mutx whoami

Note: mutx deploy create still reflects older API assumptions. See docs/cli.md for the current support matrix.

Optional: frontend verification

npm run lint
npm run build

Optional: Playwright smoke tests

npx playwright test --list

Important: current Playwright specs target https://mutx.dev, not localhost.