Installation

MuseForge ships as a single Docker image. You need an NVIDIA GPU with at least 6 GB of VRAM, Docker with the NVIDIA Container Toolkit, and room for model weights — plan for 150 GB, more if you collect models. AMD GPUs and macOS are not supported; the pipeline is CUDA-only.

git clone https://github.com/fgilde/MuseForge.git
cd MuseForge
docker compose up -d

Then open http://localhost:7861.

Choosing an image

The compose file builds locally by default. To use the prebuilt image instead, swap the build block for image: ghcr.io/fgilde/museforge:latest in docker-compose.yml. The published image is the runtime target, meaning without the compiled SageAttention kernels — it is fully functional and falls back to sdpa attention.

GPUs other than 30xx/40xx

The default build targets CUDA compute capabilities 8.0, 8.6 and 8.9. For other cards, pass your own list:

docker build --build-arg CUDA_ARCHITECTURES="8.6;8.9;12.0" -t museforge .

Your first generation

1. Open http://localhost:7861 and dismiss the welcome dialog.
2. In the right-hand dock, pick a mode: Image is the fastest way to see something work.
3. Choose a model at the bottom of the dock. Anything marked as not downloaded will fetch its weights on first use.
4. Type a prompt and press Forge.
5. Watch the queue tile in the gallery. Progress, the current step and any error appear there; the finished file lands in the gallery.

A multi-line prompt in image mode submits one job per line, which is how a blueprint with several scenes produces several images rather than one.

How it fits together

Studio

The right-hand dock is the control surface: mode tabs at the top (Image, Video, Audio, Edit, Tools, Text), sub-modes below, then inputs, prompt, and the model picker with Advanced and Forge at the bottom. The gallery on the left shows the queue and every finished output, filterable by type and searchable.

Advanced settings

Resolution, steps, guidance, seed, sliding-window sizes, LoRAs and their multipliers. LoRAs are listed per architecture: a file downloaded while another model was selected will not appear here, because it genuinely cannot be loaded by this model. See LoRAs for how to fix that.

Multi-clip and extend

Video modes can chain clips into one timeline or extend an existing video. Copy prompt on an extended video offers both the last clip's prompt and the original one that started the chain.

Director

Describe a music video or a short film in one sentence. A local LLM produces a shot list, writes a prompt per shot tuned to the model that will render it, generates start frames where useful, and then runs the whole multi-clip pipeline. Everything it decides stays editable before you commit to rendering.

The LLM runs locally (Gemma-class model, roughly 5 GB, downloaded on first Director use). Nothing is sent to a cloud unless you configure an external API under Settings → Services.

Storywriter

Text → Story. Give a premise, genre, tone, point of view and a length; the pipeline plans an outline, then writes chapter by chapter, running a continuity check between them so chapter four still knows what happened in two.

Long passes appear in the activity panel at the bottom left and can be stopped there. Stopping an analysis leaves the story itself untouched.

Audiobooks

Import a document (or a story), and it is split into chapters, blocks and runs — a run is one stretch of text spoken by one voice. Assign a narrator, override individual runs where a character speaks, and render.

Emotion

Each run can carry an emotion. How it reaches the model depends on the engine: IndexTTS2 gets its native per-line tags ([sad] on every line, because it applies emotion per sentence), Qwen3 voices get it folded into their spoken instruction, and engines with no emotion channel get a temperature nudge — which is not emotion control, just the only lever available.

Effects

Passages can carry background beds and one-shot effects. The mixer ducks the bed under speech and matches loudness so a chapter does not jump in volume between passages.

Rendering and the cache

Rendering voices each run, then mixes the chapter. Voiced runs are cached, so re-rendering an unchanged chapter is close to instant and editing one passage re-voices only that passage. Output is MP3 or WAV per chapter, or a chaptered M4B for the whole book.

Voices

Audio → Voices. A voice is an engine plus its settings, saved under a name and reused by every audiobook.

Keeping a voice

A description-driven engine invents a speaker on every render — the same description does not give you the same person twice. Audition until you hear one you like, then Keep this take: that render becomes the voice's reference clip and every passage is spoken by it. Pinning a seed alone does not do this; measured, three renders with one pinned seed produced three different voices.

Your own voice

Voice from a recording takes any audio you have — recorded in the browser, uploaded, or an existing output — and turns it into a cloning voice. The clip is copied into the library's own storage, so deleting the original output later does not break the voice.

Blueprints

A blueprint is a saved recipe. Thirty-three ship with the app, labelled by kind:

Reach them from the Blueprints button in the gallery header, and save your own from any output or from the multiselect toolbar.

LoRAs

The LoRAs button opens an in-app CivitAI browser. Entries you already own are marked, and Use now wires one into a compatible model and switches you to it.

Why a LoRA sometimes cannot be used

LoRAs are stored per architecture, under loras/<arch>. A file downloaded while another model was selected lands in that model's folder, where nothing else looks for it — installed and invisible at the same time. Two things guard against the confusion this used to cause:

• A LoRA whose declared base model has no home here at all (an SDXL adapter in a video studio) is flagged before you download it.
• A misfiled file can be relocated into the folder its base model belongs in — from the browser, or over the API with POST /loras/relocate.

Submitting a generation with a LoRA that is not installed for the chosen model is rejected immediately, with a list of what is installed — rather than the generation quietly producing nothing.

REST API

Everything the UI does goes through /api/v1. Interactive documentation with the full schema for all 184 endpoints is served by the app itself at http://localhost:7861/docs; the curated reference lives in docs/API.md.

# submit a generation
curl -X POST http://localhost:7861/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"model_type":"t2v","prompt":"a lighthouse at dusk","video_length":81}'

# poll it
curl http://localhost:7861/api/v1/status/<job_id>

# download the result
curl -O http://localhost:7861/api/v1/file/<filename>

MCP for agents

MuseForge speaks the Model Context Protocol over streamable HTTP at /mcp, in the same process as the UI — no second service to run. Seventy-six tools cover generation, jobs, outputs, stories, audiobooks, voices, LoRAs and blueprints.

claude mcp add --transport http museforge http://localhost:7861/mcp

Or in an mcp.json-style configuration:

{
  "mcpServers": {
    "museforge": { "type": "http", "url": "http://localhost:7861/mcp" }
  }
}

Set MUSEFORGE_API_TOKEN to require Authorization: Bearer <token> on /mcp. The UI's own REST calls stay tokenless.

Worked examples

A document in, an audiobook out

Entirely over MCP, no UI:

1. upload_document — hand over the file.
2. audiobook_create then audiobook_import — project and text.
3. list_voices and audiobook_import_voice — pick the narrator.
4. audiobook_plan — confirm every run has a voice.
5. audiobook_render — then poll job_status.

Story first, then read it

story_start → poll story_status → audiobook_from_story, which replaces the create and import steps.

Anything without a tool

api_request("GET", "/openapi.json") returns the full schema, and api_request can call any endpoint directly.

Storage & workspaces

All state lives in named Docker volumes, so rebuilding the image never touches your data:

Workspaces partition outputs per project and are switched from the gallery header. default is the outputs folder itself and cannot be deleted.

Updating

git pull
docker compose up -d --build

To pull in an upstream Maestro release, merge it — MuseForge has real git ancestry with upstream, so this is an ordinary three-way merge:

git remote add upstream https://github.com/Blizaine/Maestro.git   # once
git fetch upstream && git merge upstream/main

The VERSION file records which upstream release the engine is level with.

Exposure & security

• Bind to loopback only by changing the port mapping to 127.0.0.1:7861:7860.
• Set MUSEFORGE_API_TOKEN if agents reach /mcp from elsewhere.
• Put a reverse proxy with real authentication in front of it before exposing it to a network you do not control.

Troubleshooting

A generation ends with no file

Read the message on the job tile — failures now carry the reason. The most common cause used to be a LoRA that could not load; that is refused up front now, naming the file and what is installed instead.

My downloaded LoRA does not appear in Advanced

It is in another architecture's folder. Open the LoRA browser, find it under the installed entries, and relocate it. See LoRAs.

An MCP tool call times out

Check the URL first: it must be the address the UI answers on plus /mcp. Ask the instance itself with GET /api/v1/mcp/info.

A story says "crashed"

The process went away mid-run — a restart or an out-of-memory kill. The message names the phase it never came back from. Finished chapters are kept, so extend continues from the last one.

Something is running and I want it to stop

The activity panel at the bottom left lists every long-running job — generations, story passes and model downloads — each with a stop button.

Out of VRAM

Lower the resolution or the sliding-window size, or pick a smaller model variant. Auto-tune profiles the GPU on first launch and chooses offload and quantization settings; low-VRAM cards work, just slowly.