Quickstart Guide

Get Mix up and running in 5 minutes with this step-by-step guide.

Mix is an open-source desktop platform for multimodal AI agents, multimodal claude code, where all project data is stored as plain text and native media files - absolutely no lock-in.

Prerequisites

Before starting, ensure you have:

• Go 1.19+ - For the backend service
• Node.js 18+ - For the frontend application
• Git - To clone the repository

Step 1: Clone and Setup

# Clone the repository
git clone <repository-url>
cd mix

# Install dependencies first
make install

# Start development environment (this starts both frontend and backend)
make dev

The make dev command will:

• Start the Go backend HTTP server (typically on port 8080)
• Launch the Tauri desktop application (mix_tauri_app/)
• Enable auto-reload with Go Air for hot reloading
• Provide unified logging with timestamps and color-coded by service in dev.log
• Forward browser console logs to terminal via mix_tauri_app/src/vite-console-forward-plugin.ts

Step 2: Configure Authentication

Mix requires AI model configuration for both main and sub-agents.

Option A: Claude Code Account (Recommended)

If you have a Claude Code account:

1. Install and start the application with make dev
2. Use the /login command in the UI after installation to authenticate
3. The system will automatically detect your Claude Code authentication

Option B: API Keys

Set your API keys in the .env file:

# Required: Claude Sonnet 4 for main agent
ANTHROPIC_API_KEY="your-anthropic-api-key"

# Required: Gemini 2.5-flash for analyzing images, videos and audio
GEMINI_API_KEY="your-gemini-api-key"

Configuration Hierarchy: Mix uses a global → local configuration hierarchy:

1. Global config: ~/.mix.json - System-wide defaults
2. Local config: ./.mix.json - Project-specific overrides (merges with global)

Create a .mix.json file for explicit model configuration:

{
  "agents": {
    "main": {
      "model": "claude-sonnet-4",
      "maxTokens": 4096
    },
    "sub": {
      "model": "claude-sonnet-4", 
      "maxTokens": 2048
    }
  }
}

Step 3: Verify Installation

Once everything is running, you should see:

1. Backend logs indicating the HTTP server is running (typically on port 8080)
2. Frontend application launches automatically
3. Unified logging in the terminal showing both frontend and backend activity

Check the logs:

# View recent logs (last 100 lines)
make tail-log

All development output (backend compilation, frontend builds, runtime logs, browser console) flows through a single log file for streamlined AI-assisted debugging.

Step 4: Test Your First Workflow

Desktop App Mode

1. Open the Mix desktop application (should launch automatically)
2. Try a simple prompt: "Analyze this image and describe what you see"
3. Upload an image and see the multimodal analysis in action

CLI Mode (Alternative)

# Test CLI mode
./mix -p "Create a simple video title animation"

# Test HTTP server mode
./mix --http-port 8080

Common Commands

# Install dependencies first
make install

# Development (starts both frontend and backend with auto-reload)
make dev

# Production build
make build

# Clean build artifacts
make clean

# View current logs (last 100 lines)
make tail-log

# CLI usage
./mix -p "Your prompt here"

# HTTP server mode (for integrations)
./mix --http-port 8080

Troubleshooting

Build Issues

• Ensure Go 1.19+ and Node.js 18+ are installed
• Run make clean and try again
• Check that you're in the project root directory

Authentication Issues

• Verify your Claude Code account is active
• Check environment variables are set correctly
• Ensure API keys have sufficient credits/permissions

Connection Issues

• Check if ports 8080 (backend) are available
• Verify firewall settings allow local connections
• Review logs with make tail-log

Example Use Cases

Mix supports various multimodal workflows:

1. Creating remotion titles - Generate animated video titles and graphics
2. Blender video editing - Automate 3D modeling and video editing workflows
3. Video analysis - Ask for highlights and insights from video content
4. Session recording analysis - Analyze user interactions and behavior

Available Tools

• Blender integration - 3D modeling and animation workflows
• Pixelmator tools - Advanced image editing capabilities
• Multimodal analyzer - Process images, videos, and audio with AI

Next Steps

Now that Mix is running, explore these areas:

Development Notes

• Auto-reload: Backend uses Go Air for hot reloading, frontend uses Vite's built-in HMR
• Unified Logging: All process output is aggregated with timestamps and color-coded by service in dev.log
• File storage: All project data is stored as plain text and native media files - absolutely no lock-in
• HTTP Architecture: The backend is an HTTP server, meaning the frontend is just one of possible clients

Get Help

If you encounter issues:

1. Check the troubleshooting guide
2. Review logs with make tail-log
3. Verify your configuration matches this guide
4. Check that all prerequisites are installed correctly