Quickstart

Get muxAI running locally in minutes. Choose the install script or set everything up manually.

Prerequisites

Before you begin, make sure you have:

• Node.js 18+ - nodejs.org
• pnpm - Install with npm i -g pnpm
• Claude CLI - claude.ai/code
• Git - To clone the repository

Choose your path

Install script

The install script checks dependencies, sets up your .env, configures the database, builds the project, and gives you a choice of run mode (PM2 or manual).

macOS / Linux

git clone https://github.com/muxai-io/muxai.git
cd muxai
bash install/install.sh

On Windows, if you get a script execution error, run this first in your PowerShell session:

Set-ExecutionPolicy Bypass -Scope Process

This allows scripts to run for the current session only.

The script will prompt you for:

1. Missing dependencies - Offers to install Node.js, pnpm, and Claude CLI if not found
2. Database type - Embedded (zero setup), Docker, or external PostgreSQL
3. Run mode - PM2 (background service) or manual (start/stop yourself)

Pass --yes (bash) or -Yes (PowerShell) to skip all prompts and use defaults: embedded database + manual run mode.

Once the script finishes, jump to Verify the install.

Manual setup

1. Clone and install dependencies

git clone https://github.com/muxai-io/muxai.git
cd muxai
pnpm install

2. Configure environment

cp .env.example .env

Open .env and set the required values:

.env

# Database - pick one:
# Leave commented out for embedded (zero setup, recommended)
# DATABASE_URL=embedded

# Or point to your own PostgreSQL:
# DATABASE_URL="postgresql://user:password@localhost:5432/muxai"

# API
API_PORT=3001
API_KEY=your-secret-key-change-me
NEXT_PUBLIC_API_URL=http://localhost:3001

# Internal secrets
MUXAI_INTERNAL_SECRET=muxai-internal-secret-change-me
WALLET_ENCRYPTION_KEY=change-me-64-hex-chars

# Claude CLI
CLAUDE_CLI_PATH=claude

Generate secure values for the secrets:

# Run this three times, once for each secret
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Replace API_KEY, MUXAI_INTERNAL_SECRET, and WALLET_ENCRYPTION_KEY with the generated values.

3. Database setup

Embedded PostgreSQL (recommended)

No setup needed. Leave DATABASE_URL commented out or set to embedded in your .env. The API starts an in-process PGlite instance automatically on first run.

Docker

docker compose up -d db

Then set in .env:

DATABASE_URL="postgresql://muxai_user:muxai_password@localhost:5432/muxai"

Push the schema:

pnpm --filter @muxai/api db:push

External PostgreSQL

Point DATABASE_URL to your instance:

DATABASE_URL="postgresql://user:password@your-host:5432/muxai"

Push the schema:

pnpm --filter @muxai/api db:push

4. Build

pnpm --filter @muxai/api build
pnpm --filter @muxai/web build

5. Start

pnpm start

Or for development with hot reload (no build needed):

pnpm dev

Verify the install

Once running, confirm both services are up:

Service	URL
Web portal	http://localhost:3000
API	http://localhost:3001

Check the API health endpoint:

curl http://localhost:3001/api/health

Updating

Pull the latest changes and rebuild:

macOS / Linux

bash install/update.sh

Or manually:

git pull
pnpm install
pnpm --filter @muxai/api build
pnpm --filter @muxai/web build

If you’re using PM2, restart after updating:

pm2 restart ecosystem.config.js --update-env