Skip to content

INSTALLATION.md

Latest commit

 

History

History
558 lines (399 loc) · 14.1 KB

INSTALLATION.md

File metadata and controls

558 lines (399 loc) · 14.1 KB
Raw

Installation guide

This guide covers every step to get muse2api running, from zero to your first API call.

Table of contents

  1. Prerequisites
  2. Installation
  3. Importing your muse.ai account
  4. Connecting an API client
  5. Configuration reference
  6. Nginx reverse proxy
  7. Troubleshooting
  8. Updating
  9. Uninstalling

Prerequisites

Requirement Windows Linux / Docker
Python 3.10+ 3.10+ (Docker handles the install)
Browser Chrome or Edge (auto-detected) Chromium (apt install chromium)
Internet Required Required
muse.ai account Required (free account at muse.ai) Same

Do I need a muse.ai Pro/paid account? No. A free account works. The API wraps the web interface, so whatever the web UI lets you do, the API exposes.

Installation

Option 1: Docker / Linux VPS

This option suits always-on VPS deployment with no manual Python setup.

Step 1: Install Docker

curl -fsSL https://get.docker.com | sh

Or follow the official guide at docs.docker.com/get-docker.

Step 2: Clone and configure

git clone https://github.com/its-benjamin/muse2api.git
cd muse2api
cp .env.example .env

Edit .env to set your own admin key (optional but recommended):

nano .env
# Set: MUSE2API_KEY=m2a_your_secure_key_here

Step 3: Start

docker compose up -d

Step 4: Open the admin panel

http://<YOUR_SERVER_IP>:18610

Check the logs if you need the auto-generated key:

docker compose logs muse2api | grep "Admin key"

Step 5: (Optional) Nginx reverse proxy

See Nginx reverse proxy below if you want HTTPS or a custom domain.

Option 2: Linux bare-metal

Use this for a VPS without Docker, or for custom deployments.

Step 1: Install system dependencies

sudo apt-get update
sudo apt-get install -y chromium python3 python3-pip python3-venv git

Step 2: Clone the repo

git clone https://github.com/its-benjamin/muse2api.git
cd muse2api

Step 3: Set up Python environment

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Step 4: Configure

cp .env.example .env
nano .env   # set MUSE2API_KEY and other options

Step 5: Run as a systemd service (auto-start on reboot)

sudo cp deploy/muse2api.service /etc/systemd/system/
# Edit the service file to match your paths:
sudo nano /etc/systemd/system/muse2api.service
sudo systemctl daemon-reload
sudo systemctl enable --now muse2api

Check status:

sudo systemctl status muse2api
journalctl -u muse2api -f

Or run manually for testing:

source venv/bin/activate
python run.py

Option 3: Windows (local)

Use this for personal use on your own PC: no server, no Docker, no command line after setup.

Step 1: Install Python 3.10+

  1. Go to python.org/downloads
  2. Download the latest Python 3.x installer
  3. Run it and check "Add python.exe to PATH" on the first screen
  4. Click Install Now

Step 2: Install Chrome or Edge

Chrome and Edge are auto-detected. If you already have either installed, skip this step.

Step 3: Download muse2api

Option A, with Git:

git clone https://github.com/its-benjamin/muse2api.git

Option B, without Git:

  • Click the green Code button on GitHub, then Download ZIP
  • Extract the ZIP anywhere (e.g. C:\muse2api)

Step 4: Launch

Double-click start-windows.bat in the extracted folder.

If Windows Defender SmartScreen warns you, click More info, then Run anyway. This only appears the first time.

The first launch installs Python packages automatically (takes ~1 minute). You'll see:

muse2api started — http://127.0.0.1:18610
Admin key: m2a_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 5: Open the admin panel

Open your browser and go to:

http://127.0.0.1:18610

The key is shown in the console window. Copy it and paste it into the admin panel login field.

Important: Do not run as Administrator

muse2api launches Chrome in the background. Chrome exits immediately when launched from an elevated process. If you see Chrome errors, run start-windows.bat as a normal user.

Importing your muse.ai account

muse2api needs your muse.ai session cookies to act on your behalf. You get these from your browser after logging in. There are three ways:

Option A: Chrome / Edge extension

This is the easiest method. The extension reads your cookies automatically, no F12 or manual copy-paste needed.

Step 1: Load the extension

  1. Open Chrome or Edge
  2. Go to chrome://extensions
  3. Toggle Developer mode on (top-right corner)
  4. Click Load unpacked
  5. Select the extension folder inside the muse2api directory

Step 2: Log in to muse.ai

Open muse.ai and log in until you see the main chat interface.

Step 3: Import

  1. Click the muse2api extension icon in your browser toolbar
  2. Fill in:
    • Service URL: http://127.0.0.1:18610 (or your server IP)
    • API Key: your MUSE2API_KEY from the console
  3. Click Read and import

You should see a success message. The account now appears in the admin panel.

Option B: Tampermonkey userscript

Use this if you prefer Firefox, Safari, or don't want to enable Developer mode.

Step 1: Install Tampermonkey

Step 2: Create the userscript

  1. Click the Tampermonkey icon, then Create a new script
  2. Delete the default template
  3. Paste the entire contents of tools/muse2api_cookie_importer.user.js
  4. Press Ctrl+S to save

Step 3: Import

  1. Open muse.ai and log in
  2. A floating ⚡ Import to muse2api button appears at the bottom-right
  3. Right-click it to configure your service URL and API key
  4. Left-click to import

Option C: Manual cookie paste

If neither extension works, you can paste cookies manually from your browser's DevTools.

Step 1: Open DevTools on muse.ai

  1. Open muse.ai and log in
  2. Press F12 to open DevTools
  3. Go to the Application tab, then Cookies, then https://muse.ai

Step 2: Copy the key cookies

You need at least: hatch_sess, hatch_gw, hatch_vml, hatch_native_auth_device

Copy the whole cookie string from the Network tab:

  1. Press F5 to reload
  2. In the Network tab, click any request to muse.ai
  3. Find the Cookie: request header
  4. Copy the entire value

Step 3: Import via admin panel

  1. Open the admin panel, then Accounts, then Add account
  2. Paste the cookie string into the input field
  3. Click Import

Connecting an API client

Once you have an account imported, you can use any OpenAI- or Anthropic-compatible client.

Claude Code & Claude Agent SDK

Point Claude Code at muse2api:

export ANTHROPIC_BASE_URL="http://127.0.0.1:18610"
export ANTHROPIC_API_KEY="m2a_your_key_here"
claude

Anthropic Python SDK

import anthropic

client = anthropic.Anthropic(
    base_url="http://127.0.0.1:18610",
    api_key="m2a_your_key_here",
)

message = client.messages.create(
    model="claude-3-5-sonnet",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)

For streaming:

with client.messages.stream(
    model="claude-3-5-sonnet",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:18610/v1",
    api_key="m2a_your_key_here",
)

response = client.chat.completions.create(
    model="muse-spark",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

For streaming:

with client.chat.completions.stream(
    model="muse-spark",
    messages=[{"role": "user", "content": "Tell me a story"}],
) as stream:
    for chunk in stream:
        print(chunk.choices[0].delta.content or "", end="", flush=True)

Cursor / Continue / VS Code extensions

In the settings for your AI extension:

Setting Value
API Base URL / Endpoint http://127.0.0.1:18610/v1
API Key your MUSE2API_KEY
Model muse-spark (or gpt-4o, gpt-4, etc.; all route to Muse)

Cursor:

  • Settings, then Models, then Add model, then Custom
  • Base URL: http://127.0.0.1:18610/v1
  • API Key: your key

Continue (VS Code):

Edit ~/.continue/config.json:

{
  "models": [
    {
      "title": "Muse via muse2api",
      "provider": "openai",
      "model": "muse-spark",
      "apiBase": "http://127.0.0.1:18610/v1",
      "apiKey": "m2a_your_key_here"
    }
  ]
}

SillyTavern / other chat UIs

In SillyTavern:

  1. API: OpenAI
  2. API URL: http://127.0.0.1:18610/v1
  3. API Key: your MUSE2API_KEY
  4. Model: muse-spark

curl

curl http://127.0.0.1:18610/v1/chat/completions \
  -H "Authorization: Bearer m2a_your_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"muse-spark","messages":[{"role":"user","content":"Hi"}]}'

Configuration reference

All settings go in .env (copy from .env.example):

# Required for production — leave blank to auto-generate on first start
MUSE2API_KEY=m2a_your_secure_key_here

# Network
MUSE2API_HOST=0.0.0.0          # 127.0.0.1 = local only
MUSE2API_PORT=18610

# Browser
MUSE2API_CHROMIUM=              # leave blank to auto-detect Chrome/Edge
MUSE2API_CDP_PORT=19210         # internal Chrome DevTools port
MUSE2API_BROWSER_IDLE_MIN=0    # 0 = always warm; 10-15 = free ~700MB when idle

# Timeouts (seconds)
MUSE2API_CHAT_TIMEOUT=300
MUSE2API_IMAGE_TIMEOUT=240
MUSE2API_VIDEO_TIMEOUT=600

# Advanced
MUSE2API_PUBLIC_BASE=           # public URL if behind a reverse proxy
MUSE2API_HTTP2=0                # 1 = experimental HTTP/2
MUSE2API_KEEPALIVE_DISABLED_ACCOUNTS=0  # 1 = also keepalive disabled accounts

Nginx reverse proxy

If you're serving muse2api on a VPS behind Nginx with HTTPS:

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass          http://127.0.0.1:18610;
        proxy_read_timeout  600s;
        proxy_send_timeout  600s;
        proxy_buffering     off;               # required for SSE streaming
        client_max_body_size 64M;              # for image uploads
        proxy_set_header    Host              $host;
        proxy_set_header    X-Real-IP         $remote_addr;
        proxy_set_header    X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Proto $scheme;
    }
}

proxy_read_timeout 600s prevents 502 errors on long video/image generation jobs. proxy_buffering off is required for SSE streaming. client_max_body_size 64M allows large reference image uploads.

Troubleshooting

"No accounts available" error from the API

You haven't imported a muse.ai account yet, or all accounts are flagged as unavailable. Open the admin panel, go to Accounts, and import an account, or click Test on existing accounts.

401 from /api/session

Your cookies expired. muse.ai session cookies last ~48 hours. Log into muse.ai again and re-import via the Chrome extension or Tampermonkey.

403 from /api/session

Access denied, usually a regional restriction on your VPS's IP or an account permissions issue. Try a different VPS region or a residential proxy. Re-importing the same cookies won't help.

Chrome won't launch on Windows

  • Make sure you're not running as Administrator
  • Check that Chrome or Edge is installed
  • Try setting MUSE2API_CHROMIUM to the full path, e.g. C:\Program Files\Google\Chrome\Application\chrome.exe

High RAM usage (~700 MB)

Chrome uses ~700 MB RSS. To free it when idle:

MUSE2API_BROWSER_IDLE_MIN=10

The browser stops after 10 minutes of inactivity. The next request restarts it (~5-10 s cold start).

Admin panel shows "update available" banner

Click One-click online upgrade & restart to pull the latest code and restart. Your .env and data/ are preserved.

Or manually:

# Git
git pull --ff-only && systemctl restart muse2api

# Docker
git pull --ff-only && docker compose up -d --build

"Still sending" / VM connection timeout

The muse.ai cloud VM that runs your account's browser session was suspended. The service wakes it automatically. If this keeps happening, check that keepalive is running (admin panel, then health).

Updating

Docker:

git pull --ff-only
docker compose up -d --build

Linux bare-metal:

git pull --ff-only
source venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart muse2api

Windows (start-windows.bat): Pull the latest code (or download the new ZIP) and restart start-windows.bat. Your .env and data/ are not touched.

Uninstalling

Docker:

docker compose down -v

Linux bare-metal:

sudo systemctl disable --now muse2api
sudo rm /etc/systemd/system/muse2api.service
rm -rf /opt/muse2api

Windows: Delete the muse2api folder. The Chrome profile is in muse2api-profiles/ next to the folder; delete that too.