Hangry LabsUseful tools, easy to run

Docker runtime

Build and operate the local image with Task:

task init
task start
task status

Open http://localhost:8087. task init downloads/verifies external models and builds the image; task start preserves upstream inference defaults.

The MCP music tools share port 8087 at /mcp. They return temporary HTTP audio links rather than embedding audio in tool results. task start persists all server results in data/results/studio/, mounted at /output. For registry containers, add a named output volume such as --mount type=volume,source=yue2-output,target=/output. Completed links retain their original one-hour expiry across restarts. Native/API results default to 24 hours, 10 GiB / 256 entries; running jobs do not survive. See queue/storage settings for limits, retry behavior and status endpoints. Set YUE2_API_KEY for Bearer protection on /v1 and /mcp; the MCP guide documents public link origins and the existing native/Studio access boundary.

Registry images

The publication workflow targets hangrylabs/yue2 on Docker Hub and ghcr.io/hangry-labs/yue2 on GHCR. master publishes latest to both; stable Git tags publish matching vX.Y.Z tags. The first latest publication succeeded on both registries. The GGML dependency release is separate from this runnable application image. For model downloads and Bash/PowerShell quick starts, see the README. The Docker Hub overview is maintained separately for the registry page.

The first stable release is v1.0.0. Both registries expose the verified top-level OCI index sha256:446bd69099513f8b1d762656d455826872b7221ab232aa05e907f3ada90c9b34.

With the two external model files downloaded, PowerShell:

docker run -d --name yue2 --gpus all -p 127.0.0.1:8087:8087 --mount "type=bind,source=$($PWD.Path)\data\models,target=/models,readonly" --mount type=volume,source=yue2-output,target=/output hangrylabs/yue2:v1.0.0@sha256:446bd69099513f8b1d762656d455826872b7221ab232aa05e907f3ada90c9b34

For GHCR, replace the image with ghcr.io/hangry-labs/yue2:v1.0.0@sha256:446bd69099513f8b1d762656d455826872b7221ab232aa05e907f3ada90c9b34. In Bash, use --mount "type=bind,source=$(pwd)/data/models,target=/models,readonly". The models are not included or downloaded by the server. task models prepares them. The rolling latest image follows development; the stable command pins the version tag and the top-level OCI digest verified on both registries.

See publication and visibility for the first GHCR package’s public access setting and the workflow’s post-upload digest checks.

Manual build and run

For the development RTX 5070 Ti:

docker build --build-arg CUDA_ARCHITECTURES=120a-real --build-arg BUILD_JOBS=4 -t yue2:dev .

PowerShell, from the checkout with both model files present:

docker run -d --name yue2-dev --gpus all -p 127.0.0.1:8087:8087 --mount "type=bind,source=$($PWD.Path)\data\models,target=/models,readonly" --mount type=volume,source=yue2-output,target=/output yue2:dev

For Bash, use --mount "type=bind,source=$(pwd)/data/models,target=/models,readonly". The locally built tag is yue2:dev. Models are not baked in and are not automatically downloaded by the server; task models handles that.

GGML/CUDA compilation has its own reusable stage, independent of application, UI and revision changes. task deps:build can prepare a portable dependency artifact for CI. Normal Task/CI builds download and verify the pinned public release archive; direct Docker builds use the source fallback unless a named context or artifact image is supplied. See build dependencies. The artifact contains code libraries, never model weights.

Weight-free packaging

The runtime build must pass scripts/check_no_weights.py before Docker can produce the final image. This applies to task build, direct Docker builds and the CI publication workflow. The checker inspects the assembled image filesystem, including the base image, for common weight extensions (GGUF, SafeTensors, PyTorch checkpoints, ONNX, .bin and others) and GGUF/GGML file headers even when a file has been renamed. A match or an unreadable file fails the build and identifies the offending path. Python stays in the checking stage.

The Docker context also excludes those extensions everywhere, in addition to the entire data/ directory and legacy storage paths. Model downloads and read-only runtime mounts are unaffected. These checks catch common accidental inclusions; they do not identify every possible encoding or inspect archives.

Runtime settings

Default model filenames are /models/YuE2-3B-Q8_0.gguf and /models/YuE2-Vae-F32.gguf. Default server port is 8087, backend selection is automatic, context is 24576 and batch limit is one. Models are released under the upstream strict eviction policy. No keep-loaded or reduced-context override is applied by task start.

Container arguments replace the default server arguments. Include required --model and --vae arguments and the network binding when supplying custom options. --max-seq can reduce VRAM but can reject long requests whose prompt plus token budget exceeds it. --keep-loaded retains models and requires additional VRAM.

Choose a single GPU with Docker’s --gpus device=0 instead of --gpus all. The server selects its compute backend automatically; --device CUDA0 refers to the first GPU visible inside the container, after Docker’s GPU filtering. The YUE2_* values in .env.example configure host-side Task commands, not the server’s container environment.

For optional adapters, create a host data/adapters/ directory alongside data/models/. Use this command when creating the container. PowerShell:

docker run -d --name yue2 --restart unless-stopped --gpus all -p 127.0.0.1:8087:8087 --mount "type=bind,source=$($PWD.Path)\data\models,target=/models,readonly" --mount "type=bind,source=$($PWD.Path)\data\adapters,target=/adapters,readonly" --mount type=volume,source=yue2-output,target=/output hangrylabs/yue2:v1.0.0@sha256:446bd69099513f8b1d762656d455826872b7221ab232aa05e907f3ada90c9b34

In Bash use source=$(pwd)/data/models and source=$(pwd)/data/adapters in the respective mounts. The default image command already sets --adapters /adapters. Adapter files remain external to the image.

The runtime uses non-root UID 10001. Host port is bound to localhost by the task. For a CLI run, override –entrypoint with yue-synth or another native executable and mount a writable output directory at /output. Linux output directories must be writable by the container user; the baseline runner selects the host UID.

Request defaults and lyrics

FFmpeg is included for compressed exports and broader upload support. The studio, /synth and VAE decode support nine audio output formats, while WAV retains its native encoder. Optional transcription/tokenization models stay disabled.

Requests use full score mode, a 360-second duration ceiling, 8 flow-matching steps, one composition and two acoustic variations (maximum three), random seeds, and MP3 at 128 kbps. Single-track compatibility routes and saved replays keep one rendition. The 8-step default is a deliberate Hangry Labs choice; upstream uses 32. Other inference defaults retain the upstream initialization. The standard server keeps the 24,576-token model context. The fixed test1 benchmark explicitly records 8 steps and its seeds.

The browser leaves blank numeric fields for the server to resolve. Explicit form settings override defaults. Normal Generate song uses the current words and direction, with fresh seeds unless fixed values were entered. Generated scores never fill the next request automatically. The 110 bundled examples retain upstream content and preserve generation settings when selected.

Composition input defaults to New song. To deliberately reuse musical material, select Use ABC score, Replay audio codes or Continue source. Typing a score or audio codes selects the corresponding reuse mode; editing lyrics or musical direction returns to New song. Library Edit prompt reuses text with fresh seeds, while Use this score and Replay this take load the chosen material explicitly. Transcription and tokenization update the library card without changing the current editor. Info buttons beside settings explain their effects and tradeoffs, including on touch devices.

Existing browser forms are migrated once to remove old generated conditioning and resolved replay seeds, preserving text, generation controls and the library. Reloading always starts in New song mode; deliberate reuse must be selected again. The native API continues to honor supplied scores and replay/continuation tokens. For old sparse replay files that omitted the former default, set steps: 32 explicitly to retain their original refinement setting.

Persistence and health

Storage Behavior
Host data/models/ mounted at /models Model files survive container replacement
Host data/adapters/ mounted at /adapters by task start Optional LoRA files
Browser IndexedDB/localStorage Songs, artifacts and form state
Persistent /output mount Native/API results survive until expiry (24 hours by default); MCP links last one hour
Server memory Active/queued work and small metadata only
Host data/results/ Baseline audio, requests and logs

The health check calls /health. It proves liveness, not a successful generation. task test1 performs a full model-dependent generation. See BENCHMARKS.md for measured results.

System in the browser studio shows read-only NVIDIA telemetry from GET /system/gpu. The native server uses NVML from the host driver, loaded on demand, with no shell commands or background sampler. Requests share a one-second cache and at most ten minutes of sampled history. The browser polls only while System and the document are visible; missing sensors remain null. The endpoint uses Cache-Control: no-store. CPU-only builds or containers without the NVIDIA monitoring library return an empty GPU list and an unavailable message. GPU visibility can include other workloads on the device.

GET /props now includes capabilities.transcribe, capabilities.tokenize and capabilities.vae, so optional actions can be disabled before submission. Configured model paths indicate configuration rather than current VRAM residency. Run task test:api for read-only checks against the running local server.

The image is weight-free but the general CUDA runtime base is still sizeable. Runtime library trimming remains future packaging work; there is only one image variant. CUDA/base-image and dependency terms remain applicable.