Make something with your people in it.

# Assemble Decosa Studio on this machine

You are setting up a local creative studio on ONE NVIDIA GPU: songs (MiniMax-Music3, with ACE-Step 1.5 as a fast option), images (Qwen-Image-2512) and video (Wan2.1-T2V-14B), plus the `decosa-api` queue and gallery. Only one model is on the GPU at a time. Work step by step, show me each command before you run anything with `sudo`, and stop to ask if a check fails.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
   nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
   "test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
   https://decosa.ai/samples/studio.zip (942 KB, 11 checks, synthetic or openly licensed: see `licence` in expected.json),
   show me what is in it, and run the rehearsal against the local API:
   `docker compose exec api python scripts/rehearse.py studio` (the api image carries the same bundle under /app/rehearsal/studio/;
   with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
   `python scripts/rehearse.py studio --bundle studio.zip --base-url http://127.0.0.1:<PORT>`.
   It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "the gallery lists music, images and video", "the gallery has at least one video", "every MiniMax-Music3 track carries its licence notice"). Show me
   the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
   to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
   machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## 0. Ground rules and licences
- Default models, all usable self-hosted or hosted: MiniMax-Music3 (MiniMax-Music3 Community License), ACE-Step 1.5 (MIT), Qwen-Image-2512 (Apache-2.0) and Wan2.1-T2V-14B (Apache-2.0).
- MiniMax-Music3 duties: show "MiniMax-Music3" prominently in any commercial UI that plays its output. Keep abuse and IP-infringement safeguards on any hosted service, follow the Acceptable Use Policy (Exhibit A), and get written authorization from MiniMax above USD 20M yearly revenue.
- Optional video with sound (self-host only, never for a hosted service you offer to others):
  - LTX-2.5 (LTX-2 Community License): free only below USD 10M annual revenue. Pass the licence and Attachment A on to anyone you distribute to. Item 20 bars use in a product that competes directly with the licensor's without a commercial licence.
  - MiniMax-H3 (MiniMax H3 Community License): not licensed in the US, EU, UK or South Korea. Before you download any H3 weights, **ask me to confirm** that my jurisdiction is covered, or that I hold a licence from MiniMax (api@minimax.io). If I don't confirm, skip H3 (and the H3-Turbo LoRA) and stay on Wan2.1. If you do use H3, show "Powered by MiniMax H3" and give users terms that carry its use restrictions.
- Do NOT substitute Qwen-Image-2.1 (research-only licence) or OmniVoice (non-commercial weights). Never render a real person's likeness or clone a real voice.
- Nothing leaves this machine. Bind every port to 127.0.0.1.

## 1. Check the GPU, driver and Docker
1. Run `nvidia-smi`. You need at least 48 GB of free VRAM and 64 GB or more of system RAM. Measured on an RTX PRO 6000 with about 50 GB free: ACE-Step peaked at 14.6 GB, Qwen-Image-2512 at 41.6 GB with CPU offload, and Music3 and Wan 14B both ran. Blackwell cards (sm_120) need a driver with CUDA 13.0 support.
2. If `docker` is missing, install Docker Engine (docs.docker.com). If `docker run --rm --gpus all ubuntu nvidia-smi` fails, install the NVIDIA Container Toolkit (nvidia.github.io/libnvidia-container), then run `sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker`.
3. Check disk space: the default models need about 170 GB.

## 2. Pull the models (pinned revisions)
Create `~/decosa-studio/{models,renders,worker,render,comfyui}`, run `pip install -U huggingface_hub`, then:
- `hf download Comfy-Org/MiniMax-Music-3 --revision 6baad88896848433857c170ba4f05d2ea9d5f218 --local-dir models/music3 --include "diffusion_models/minimax_music3_dit_fp16.safetensors" "text_encoders/minimax_music3_text_encoder_pruned_bf16.safetensors" "vae/minimax_music3_dav.safetensors"`. This is a repackage of MiniMaxAI/MiniMax-Music3. It is tagged Apache-2.0, but the upstream MiniMax-Music3 licence governs.
- `hf download ACE-Step/Ace-Step1.5 --revision 19671f406d603126926c1b7e2adc169acbcade22 --local-dir models/ace-step`
- `hf download Qwen/Qwen-Image-2512 --revision 25468b98e3276ca6700de15c6628e51b7de54a26 --local-dir models/qwen-image-2512`
- `hf download Wan-AI/Wan2.1-T2V-14B --revision a064a6c71f5be440641209c07bf2a5ce7a2ff5e4 --local-dir models/wan2.1-t2v-14b`. Check each safetensors file's size and SHA-256 against the Hugging Face listing. ComfyUI's `UNETLoader` wants a single file, so merge the six shards unchanged with `safetensors` (load each shard, `save_file` the combined dict to `wan2.1_t2v_14B_fp32_merged.safetensors`). Also convert the encoder: `models_t5_umt5-xxl-enc-bf16.pth` is not in ComfyUI's format, so use `split_files/text_encoders/umt5_xxl_fp16.safetensors` from `Comfy-Org/Wan_2.1_ComfyUI_repackaged` (Apache-2.0, revision 123acf1cc74bccbb9bfff8ac1ee72edc08c2341d) and keep `Wan2.1_VAE.pth` as the VAE.

## 3. Images
- `${DECOSA_REGISTRY}/decosa-api:0.1.0` (**publishing soon**). If the pull fails, build from source: `git clone <decosa-api source: on request at https://decosa.ai/contact?topic=self-host>` (access required), then `docker build -f docker/api/Dockerfile -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .`.
- Build two images locally, since no render image is published:
  - `decosa-render:local`: `python:3.12-slim` plus `ffmpeg` and `git`; `torch==2.13.0` from `https://download.pytorch.org/whl/cu130`; `diffusers` from `git+https://github.com/huggingface/diffusers@abc5e9bf71fd38f53cd471bc3acaa84bc5ecbfdc`, plus `transformers`, `accelerate`, `fastapi` and `uvicorn`; and ACE-Step (tested in its own venv on torch 2.10.0+cu128; Qwen-Image was tested on torch 2.13.0+cu130, so if the two conflict, give ACE-Step its own venv) installed with `git clone https://github.com/ace-step/ACE-Step-1.5 /opt/acestep && git -C /opt/acestep checkout 75fcfbddd5662f790defac0cb1bc27525142a7cf && pip install -e /opt/acestep`.
  - `decosa-comfyui:local`: torch 2.11.0 (cu128 was the tested build; use cu130 on Blackwell if cu128 fails), plus `git clone https://github.com/comfyanonymous/ComfyUI /opt/ComfyUI && git -C /opt/ComfyUI checkout 30bdda1ef13a3a34fce2cd2fec633f15d832122a && pip install -r /opt/ComfyUI/requirements.txt`. Add an `extra_model_paths.yaml` that maps the Music3 and Wan files into `diffusion_models`, `text_encoders` and `vae`.

## 4. The render worker (`render/app.py`, FastAPI on port 8460)
Reference implementation: decosa-api ships the same recipes in `scripts/studio_worker.py` (music, video, ACE-Step) and
`services/studio/` (`workflows/music3.api.json`, `workflows/wan21-t2v-14b.api.json`, `qwen_image.py`,
`acestep_render.py`). Read them first and reuse the two ComfyUI workflow files as they are, rather than writing the graphs
by hand. The shipped worker also works on its own: inside an api image that has `ffmpeg`, set
`DECOSA_STUDIO_WORKER_CMD=python /app/scripts/studio_worker.py` and `DECOSA_STUDIO_COMFY_URL=http://comfyui:8188`, and
music and video run through ComfyUI with no render service. Images still need the diffusers environment below.
- `POST /render` takes `{job_id, kind, prompt, params}`. One global lock runs one job at a time.
- **Sequential swap:** keep at most one model resident. Before switching, drop the diffusers pipeline (`del`, `gc.collect()`, `torch.cuda.empty_cache()`) or call ComfyUI `POST /free` with `{"unload_models":true,"free_memory":true}`. That call also clears ComfyUI's result cache, so a repeated job really re-renders.
- **Seed:** use `params.seed` if given, otherwise a random 31-bit integer. Write `/renders/<job_id>.json` with the seed, prompt, model id, revision and all sampler settings.
- **music** (default engine MiniMax-Music3; `params.engine="ace-step"` selects the fast model). Send ComfyUI this graph:
  - `UNETLoader(minimax_music3_dit_fp16)`, `CLIPLoader(minimax_music3_text_encoder_pruned_bf16, type "minimax")` and `VAELoader(minimax_music3_dav)`;
  - `MiniMaxMusic3TextEncode(caption, lyrics, seed, max_duration, cfg_scale=1.7, top_k=50)`, feeding a `ConditioningZeroOut` negative and `EmptyMiniMaxMusic3LatentAudio(seconds from the encoder)`;
  - `KSampler(seed, 30 steps, cfg 1.7, euler, simple)`, then `VAEDecodeAudio` and `SaveAudio`, then encode to MP3.
  - For ACE-Step, use `acestep.inference.generate_music` with `acestep-v15-turbo`, `acestep-5Hz-lm-1.7B` (backend `pt`), 8 steps and `infer_method="ode"`.
- **image:** load `QwenImagePipeline` in bf16 with `enable_model_cpu_offload()`. Use 50 steps, `true_cfg_scale=4.0`, `torch.Generator("cuda").manual_seed(seed)` and 1328×1328 by default.
- **video:** send ComfyUI this graph:
  - `UNETLoader(wan2.1_t2v_14B_fp32_merged)`, `CLIPLoader(umt5_xxl_fp16, type "wan")` and `VAELoader(Wan2.1_VAE.pth)`;
  - `CLIPTextEncode` for the prompt and the negative, then `ModelSamplingSD3(shift=5.0)`;
  - `EmptyHunyuanLatentVideo(832, 480, 81 frames)`, then `KSampler(seed, 50 steps, cfg 5.0, uni_pc, simple)`, `VAEDecode`, `CreateVideo(fps=16)` and `SaveVideo(mp4)`, then `ffmpeg -c copy -movflags +faststart`. Wan2.1 has no audio track.
- Write outputs with mode 0644 (the api runs as uid 10001). Return `{"file": "/renders/<job_id>.<ext>"}` or `{"error": "..."}`.
- `worker/submit.py`, mounted into the api container, reads the job JSON from stdin, POSTs it to `http://render:8460/render` with a 60-minute timeout, and prints the one JSON line it gets back.

## 5. `docker-compose.yml` (all ports on 127.0.0.1)
- `api`: `${DECOSA_REGISTRY}/decosa-api:0.1.0`, `127.0.0.1:8445:8445`, volumes `decosa-data:/data`, `./worker:/worker:ro` and `./renders:/renders:ro`. Environment: `DECOSA_STUDIO_WORKER=command`, `DECOSA_STUDIO_WORKER_CMD=python /worker/submit.py`, `DECOSA_STUDIO_VIDEO_BACKEND=wan` (local Wan2.1; the hosted service's
default is MiniMax H3 through fal, which needs a fal account), `DECOSA_CORS_ORIGIN_REGEX=^https?://(localhost|127\.0\.0\.1)(:\d+)?$`. Health check: `GET /healthz` (`asr` and `llm` may be false because studio does not use them).
- `render`: `decosa-render:local`, one GPU (`deploy.resources.reservations.devices`), `ipc: host`, `./models:/models:ro`, `./renders:/renders`, `127.0.0.1:8460:8460`. Health check: `GET /health` returns `{"ok":true,"loaded":<kind or null>}`.
- `comfyui`: `decosa-comfyui:local`, the same GPU, `./models:/models:ro`, command `python /opt/ComfyUI/main.py --listen 0.0.0.0 --port 8188 --reserve-vram 4 --disable-auto-launch`, with no host port. Health check: `GET /system_stats`.
- `api` depends on `render` being healthy; `render` depends on `comfyui` being healthy.

## 6. Smoke test
```bash
B=http://127.0.0.1:8445
T=$(curl -s -X POST $B/demo/session -H 'content-type: application/json' -d '{"vertical":"studio"}' | jq -r .token)
J=$(curl -s -X POST $B/studio/jobs -H "authorization: Bearer $T" -H 'content-type: application/json' \
  -d '{"kind":"music","prompt":"indie folk, fingerpicked acoustic guitar, warm and hopeful","params":{"seed":5501,"lyrics":"[verse]\nLights along the quay"}}' | jq -r .job_id)
until curl -s $B/studio/jobs/$J | jq -e '.status=="done" or .status=="failed"' >/dev/null; do sleep 3; done
curl -s $B/studio/jobs/$J    # expect {"status":"done","kind":"music","url":"/studio/media/jobs/<id>.mp3"}
```
Repeat with `"kind":"image"`, then `"kind":"video"` (expect minutes, not seconds, for Wan 14B). Each token allows at most 3 jobs.
Jobs survive an api restart: a queued job is queued again, and one that was running comes back `failed` with a reason
(the file `studio/jobs.json` in the data volume holds no tokens and no prompts of started jobs).

**Re-render check:** run the same music or image job twice with the same seed, and compare decoded PCM or pixels. On the reference machine, MiniMax-Music3 and Qwen-Image-2512 were bit-identical on the same GPU and software, and ACE-Step was not. Report what you measure and never claim a match you did not see.

**Gallery:** copy files into the `decosa-data` volume under `studio/media/gallery/` and list them in `studio/gallery.json` as `[{"id","kind","title","prompt","model","file":"gallery/<name>","seed","duration_s"}]`. For Music3 entries, include "Powered by MiniMax-Music3" in `model`. Do not put LTX-2.5 or MiniMax-H3 output in a gallery that others can reach.

## 7. Point the app at the local API
Set `NEXT_PUBLIC_DECOSA_API=http://127.0.0.1:8445` in the web app's `.env.local` and restart its dev server. Localhost origins are already allowed by CORS.

## 9. Troubleshooting
- **Out of memory on images:** keep CPU offload on, and drop to 1024×1024 before you cut steps.
- **Wan is very slow:** the full-precision 14B runs at about 40 s per step when memory is shared. Use 30 steps for drafts, or Wan2.1-T2V-1.3B.
- **403 on a download:** the model is gated, or `HF_TOKEN` is missing.
- **`no kernel image is available`:** torch is not a cu130 build.
- **Unknown node in ComfyUI:** the checkout is not at the pinned commit.
- **A job stays `queued` with a `note`:** `DECOSA_STUDIO_WORKER` is not `command`, or `submit.py` cannot reach `render`.
- **Gallery is empty:** a `file` in `gallery.json` does not exist under `studio/media/`.

Finish by printing a table: each service, its URL and health, the model revision on disk, and the measured time of each smoke job.