Installation Guide

This guide covers detailed installation steps, system requirements, environment configuration, and production deployment for Open Higgsfield AI.

System Requirements

Minimum Requirements

Operating System

macOS 10.15+
Windows 10/11
Linux (Ubuntu 20.04+, Debian, Fedora)

Runtime

Node.js v18.0.0 or higher
npm v9.0.0+ (comes with Node.js)

Browser

Chrome/Edge 90+
Firefox 88+
Safari 14+

Memory

2GB RAM (4GB+ recommended)
200MB disk space for dependencies

Recommended Specifications

For the best experience:

CPU: Multi-core processor (2+ cores)
RAM: 4GB+ for smooth multi-tab usage
Network: Stable internet connection (API calls to Muapi.ai)
Display: 1280×720 minimum resolution (1920×1080+ recommended)

Open Higgsfield AI runs entirely in the browser. No GPU is required on your local machine — all AI inference happens on Muapi’s servers.

Development Setup

Step 1: Install Node.js

If you don’t have Node.js installed:

macOS
Windows
Linux

Using Homebrew:

brew install node

Using the installer:

Download from nodejs.org
Run the .pkg installer
Follow the installation wizard

Using the installer:

Download from nodejs.org
Run the .msi installer
Follow the installation wizard
Restart your terminal

Using Chocolatey:

choco install nodejs

Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Fedora:

sudo dnf install nodejs

Using nvm (recommended):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

Verify the installation:

node --version  # Should print v18.0.0 or higher
npm --version   # Should print 9.0.0 or higher

Step 2: Clone the Repository

Clone Open Higgsfield AI from GitHub:

git clone https://github.com/Anil-matcha/Open-Higgsfield-AI.git
cd Open-Higgsfield-AI

Step 3: Install Dependencies

Install the required npm packages:

npm install

This installs the following dependencies from package.json:

{
  "devDependencies": {
    "autoprefixer": "^10.4.24",
    "postcss": "^8.5.6",
    "tailwindcss": "^4.1.18",
    "vite": "^5.4.0"
  },
  "dependencies": {
    "@tailwindcss/postcss": "^4.1.18",
    "@tailwindcss/vite": "^4.1.18"
  }
}

The project has minimal dependencies — just Vite for the build system and Tailwind CSS v4 for styling. No heavy frameworks!

Step 4: Start the Development Server

Launch the Vite development server:

npm run dev

Vite will start the server and display:

VITE v5.4.0  ready in 234 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

The development server includes hot module replacement (HMR), so your changes are reflected instantly without refreshing the page.

Step 5: Access the Studio

Open your browser and navigate to http://localhost:5173. You should see the Open Higgsfield AI interface with the API key authentication modal.

Vite Configuration

The project uses a minimal Vite configuration with an important proxy setup:

// vite.config.js
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
    plugins: [
        tailwindcss(),
    ],
    server: {
        proxy: {
            '/api': {
                target: 'https://api.muapi.ai',
                changeOrigin: true,
                secure: false
            }
        }
    }
});

Why the Proxy?

During development, the proxy routes all /api requests to https://api.muapi.ai to avoid CORS issues. The muapi.js client detects the environment and uses the appropriate base URL:

// src/lib/muapi.js:6
this.baseUrl = import.meta.env.DEV ? '' : 'https://api.muapi.ai';

Development: Requests go to /api/v1/... → Vite proxy → https://api.muapi.ai/api/v1/...
Production: Requests go directly to https://api.muapi.ai/api/v1/...

Environment Configuration

API Key Storage

Your Muapi API key is stored in the browser’s localStorage under the key muapi_key:

// src/components/AuthModal.js:50
localStorage.setItem('muapi_key', key);

// src/lib/muapi.js:10-12
getKey() {
    const key = localStorage.getItem('muapi_key');
    if (!key) throw new Error('API Key missing. Please set it in Settings.');
    return key;
}

Your API key is never sent to any server except Muapi.ai for authentication. It stays in your browser’s localStorage and is not included in the source code or version control.

Generation History

Generation history is also stored in localStorage under the key muapi_history:

// From project_knowledge.md:54-57
// History:
//   - Stored in localStorage key `muapi_history`
//   - Slides in from the right sidebar
//   - Thumbnails are clickable to re-view; hover to download

Upload History

Uploaded reference images are tracked in uploadHistory.js and stored locally:

// src/lib/uploadHistory.js manages:
// - localStorage CRUD operations
// - Canvas thumbnail generation
// - Upload history persistence

To clear all data, open your browser’s developer console and run:

localStorage.clear();

Then refresh the page.

Production Build

Building for Production

Create an optimized production build:

npm run build

Vite will:

Bundle and minify all JavaScript
Process and optimize CSS with Tailwind
Generate optimized assets
Output everything to the dist/ directory

Expected output:

vite v5.4.0 building for production...
✓ 142 modules transformed.
dist/index.html                   1.23 kB │ gzip: 0.65 kB
dist/assets/index-a3b4c5d6.css   45.67 kB │ gzip: 8.91 kB
dist/assets/index-x7y8z9w0.js    89.34 kB │ gzip: 28.45 kB
✓ built in 1.84s

Preview the Production Build

Test the production build locally:

npm run preview

Vite will serve the dist/ folder at http://localhost:4173.

Deployment Options

Deploy to Vercel

Install Vercel CLI

npm install -g vercel

Deploy

vercel

Follow the prompts to link your project and deploy.

Deploy to Netlify

Build the project

npm run build

Deploy the dist folder

Drag and drop the dist/ folder to Netlify Drop, or use the Netlify CLI:

npm install -g netlify-cli
netlify deploy --prod --dir=dist

Deploy to GitHub Pages

Update vite.config.js

Add a base property for your repository:

export default defineConfig({
    base: '/Open-Higgsfield-AI/',  // Your repo name
    // ... rest of config
});

Build and deploy

npm run build
npm install -g gh-pages
gh-pages -d dist

Self-Hosting with Nginx

Build the project

npm run build

Copy to web root

sudo cp -r dist/* /var/www/html/

Configure Nginx

Create /etc/nginx/sites-available/openhiggsfield:

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Enable and restart

sudo ln -s /etc/nginx/sites-available/openhiggsfield /etc/nginx/sites-enabled/
sudo systemctl restart nginx

Troubleshooting

Common Issues

”API Key missing” Error

Symptom: Error message when trying to generate. Solution:

Open Settings from the header
Clear any existing API key
Close the settings modal
Try generating again — the auth modal should appear
Enter a valid Muapi API key starting with sk-

CORS Errors in Development

Symptom: Console errors about CORS when making API requests. Solution: Make sure the Vite proxy is configured correctly in vite.config.js:

server: {
    proxy: {
        '/api': {
            target: 'https://api.muapi.ai',
            changeOrigin: true,
            secure: false
        }
    }
}

Restart the dev server after making changes.

Blank Page After Build

Symptom: Production build shows a blank page. Solution: If deploying to a subdirectory, add a base path to vite.config.js:

export default defineConfig({
    base: '/your-subdirectory/',
    // ...
});

Generation Hangs or Times Out

Symptom: “Generating…” state never completes. Solution:

Check your internet connection
Verify your Muapi API key is valid and has credits
Check the browser console for error messages
The polling timeout is 2 minutes for images, 4 minutes for videos (see muapi.js:120)

// src/lib/muapi.js:120
async pollForResult(requestId, key, maxAttempts = 60, interval = 2000) {
    // 60 attempts × 2 seconds = 2 minutes timeout

Port Already in Use

Symptom: Error: Port 5173 is already in use Solution: Either stop the other process using that port, or specify a different port:

npm run dev -- --port 3000

Module Not Found Errors

Symptom: Import errors or “module not found” during build. Solution:

Delete node_modules/ and package-lock.json

Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Browser Compatibility Issues

Safari localStorage Issues

Symptom: API key not persisting in Safari Private Mode. Solution: Safari disables localStorage in Private Browsing mode. Use a regular browser window or a different browser.

Firefox CSP Warnings

Symptom: Content Security Policy warnings in Firefox console. Solution: These are harmless warnings during development. They won’t appear in production builds.

Getting Help

If you encounter issues not covered here:

GitHub Issues

Report bugs or request features on GitHub

Medium Article

Read the full technical deep dive

Check the browser console (F12 → Console tab) for detailed error messages. The app logs all API requests and responses with the [Muapi] prefix.

Next Steps

Quickstart

Generate your first image or video

Image Studio

Master text-to-image and image-to-image generation

Video Studio

Create stunning AI-generated videos

Cinema Studio

Use professional camera controls

Get Started

Core Features

Guides

​Installation Guide

​System Requirements

​Minimum Requirements

Operating System

Runtime

Browser

Memory

​Recommended Specifications

​Development Setup

​Step 1: Install Node.js

​Step 2: Clone the Repository

​Step 3: Install Dependencies

​Step 4: Start the Development Server

​Step 5: Access the Studio

​Vite Configuration

​Why the Proxy?

​Environment Configuration

​API Key Storage

​Generation History

​Upload History

​Production Build

​Building for Production

​Preview the Production Build

​Deployment Options

​Deploy to Vercel

​Deploy to Netlify

​Deploy to GitHub Pages

​Self-Hosting with Nginx

​Troubleshooting

​Common Issues

​”API Key missing” Error

​CORS Errors in Development

​Blank Page After Build

​Generation Hangs or Times Out

​Port Already in Use

​Module Not Found Errors

​Browser Compatibility Issues

​Safari localStorage Issues

​Firefox CSP Warnings

​Getting Help

GitHub Issues

Medium Article

​Next Steps

Quickstart

Image Studio

Video Studio

Cinema Studio

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Minimum Requirements

Recommended Specifications

Development Setup

Step 1: Install Node.js

Step 2: Clone the Repository

Step 3: Install Dependencies

Step 4: Start the Development Server

Step 5: Access the Studio

Vite Configuration

Why the Proxy?

Environment Configuration

API Key Storage

Generation History

Upload History

Production Build

Building for Production

Preview the Production Build

Deployment Options

Deploy to Vercel

Deploy to Netlify

Deploy to GitHub Pages

Self-Hosting with Nginx

Troubleshooting

Common Issues

”API Key missing” Error

CORS Errors in Development

Blank Page After Build

Generation Hangs or Times Out

Port Already in Use

Module Not Found Errors

Browser Compatibility Issues

Safari localStorage Issues

Firefox CSP Warnings

Getting Help

Next Steps