genai-studio — Build Recipe

Take a bare machine to a running slice of a self-hosted generative-AI studio: AssetForge, a unified web app that generates text, images, music, 3D previews, and office documents (5 pipelines, ~30 backend entries, ~20 output formats including .docx/.pptx/.xlsx) through one interface — with a persistent job queue, live Socket.IO log streaming, a history browser, and a gallery — plus two bundled model microservices: MusicGen (text→music) and Shap-E (text→3D rotating-GIF preview). Key-free by default: the music pipeline works out of the box on CPU, no API keys, no GPU.

This is a partial clone of a larger personal studio — 3 of its 7 services ship here; the other 4 are deliberately left out (named and explained under Known limitations).

Status: ✅ Verified 2026-08-02 — built from this clone on a Linux Docker host (docker compose up -d --build). First boot clean (healthy containers, empty job list); a key-free 5-second music job ran end-to-end on CPU (queued → MusicGen-small download → generation in ~351 s total → real 316 KB PCM WAV downloaded via the API); a text job with no LLM configured failed honestly with the "LITELLM_URL not configured" message while the app stayed healthy; the single-concurrency queue behaved as designed; and with --profile 3d a Shap-E text→3D job produced a real rotating GIF on CPU (~11 min warm — the first-ever request also downloads ~3.4 GB of weights and needs the 30-minute budget documented below); and with LITELLM_URL pointed at an OpenAI-compatible endpoint the text pipeline generated a real markdown asset end-to-end (verified against a LiteLLM gateway with a disposable key, revoked after the test). Browser pass: SPA renders, the History and Gallery views show the generated assets, 0 console errors. The prebuilt tarball (docker save of all three images) size is recorded in ../PREBUILT_IMAGES.md. The clean clone lives in clone/.

Sensitive data: none. Post-rotation the sources were already key-free (env-only per-service keys); home-server/tailnet/LAN identifiers were scrubbed; no runtime databases or outputs ship — and the studio services that hold family data (StoryForge, TTS Studio) are deliberately not part of this clone.

What it is

Three containers (only the first two run by default):

The frontend is a hand-built vanilla-JS SPA (no build step); backend/format choices are server-declared capability matrices, so the UI renders its forms from the API. Job logs are buffered in SQLite and replayed to late-joining WebSocket subscribers.

Prerequisites

New machine? See ../SETUP.md. Then, per tier:

Configuration — nothing required

docker compose up needs no .env and no keys. What works at each level:

All documented one line at a time in clone/.env.example.

Tier 1 — Run the prebuilt containers (recommended)

Availability: the prebuilt images are available on request — they are not published or linked anywhere. Ask Kevin for them, or build from source via Tier 2.

docker load -i genai-studio-clone-image.tar   # loads all three images
cd clone
docker compose up -d                          # → http://localhost:8212  (no --build)

To produce the tarball on a machine that has built the images (Tier 2): docker save genai-studio-assetforge genai-studio-music-gen genai-studio-shap-e -o genai-studio-clone-image.tar. The model-service images are honestly large — they carry a full PyTorch base.

Tier 2 — Build from source

cd clone
docker compose up -d --build                # → http://localhost:8212
curl -s localhost:8212/health               # → {"status":"ok","service":"assetforge",...}
curl -s localhost:8208/health               # → {"loaded":false,"model":"facebook/musicgen-small","status":"ok",...}

Open http://localhost:8212 → Audio → MusicGen Small (Local) → WAV → set duration ~10 s → a prompt like "upbeat lo-fi hip-hop with jazz chords" → Generate, and watch the live log stream. The first request downloads and loads the model (a few minutes); after that, expect roughly real-time×8–20 on CPU — ~4–5 minutes for a 30-second clip, proportionally less for short clips. The app boots with an empty job list; History and Gallery fill as you generate.

Tier 3 — Bare-metal (three processes)

AssetForge (needs Node 20+ and ffmpeg on PATH):

cd clone/assetforge
npm install --omit=dev
DATA_DIR=./data OUTPUT_DIR=./outputs TEMP_DIR=./temp \
  MUSIC_GEN_URL=http://localhost:8208 SHAP_E_URL=http://localhost:8209 \
  node server.js                            # → http://localhost:8212

music-gen / shap-e (Python 3.10+; CPU-only PyTorch is fine):

cd clone/music-gen           # or clone/shap-e
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt
python app.py                               # :8208 (music-gen) / :8209 (shap-e)

On Windows, set the same variables with $env: before node server.js.

Optional extras (all off by default)

• Shap-E text→3D — docker compose --profile 3d up -d --build. Key-free and CPU-capable, but slow: ~5–7 minutes per GIF at the low end (16 steps, small frame size; CPU-dependent — the verified host measured ~7); the UI's default 64 steps takes proportionally longer. It auto-uses an NVIDIA GPU if you uncomment the deploy block in docker-compose.yml (fp16 on modern GPUs, fp32 on older ones — the service picks by compute capability).
• LLM text + documents — point LITELLM_URL at any OpenAI-compatible endpoint. Local key-free path with Ollama:

bash # in clone/.env LITELLM_URL=http://host.docker.internal:11434 # no /v1 — the app appends /v1/chat/completions # (Linux: if host.docker.internal doesn't resolve, use your host's LAN IP) LITELLM_API_KEY=ollama LITELLM_MODEL=llama3.2 # forces one model for all text/document backends

With a LiteLLM gateway that defines the app's model aliases (claude-sonnet, gemini-flash, …) you can leave LITELLM_MODEL unset and the per-backend dropdown routes to different models. - Images — HF_TOKEN (HuggingFace, free tier exists) unlocks FLUX.1-Schnell and SDXL; OPENAI_API_KEY unlocks DALL-E 3. - External 3D/image services — COMFYUI_URL (image jobs silently prefer a healthy ComfyUI over HF), TRIPOSR_URL (image→GLB), BLENDER_HUB_URL (LLM-written Blender scripts — pairs with the blenderhub recipe), ACE_STEP_URL (long-form music, 10–600 s), TRIPO_API_KEY/MESHY_API_KEY (cloud image→GLB). Each is health-gated or fails with a clear message.

Verify

curl -s localhost:8212/health                       # queue state, uptime
curl -s localhost:8212/api/backends/audio           # backend matrix (server-declared)
curl -s localhost:8208/health                       # music-gen up
# end-to-end key-free music job (short clip to keep CPU time reasonable):
curl -s -X POST localhost:8212/api/jobs -H 'Content-Type: application/json' \
  -d '{"assetType":"audio","backend":"music-gen","format":"wav",
       "prompt":"calm piano melody","options":{"duration":5}}'
# poll GET /api/jobs/<jobId> until "status":"completed", then download:
#   GET /api/assets/<jobId>/download

Tests (assetforge ships a small node:test suite with mocked HTTP): cd clone/assetforge && npm install && node --test test/local-backends.test.js — 3 tests, all passing as shipped.

What was stripped from the personal version (de-identification + minimalism)

• The remote-GPU backends. The original studio could reach a GPU PC over the LAN for ComfyUI, TripoSR, and Bark (LAN IPs set via compose env). Those backends stay in the capability matrix but now default to unset env vars — the health poller simply reports them down and jobs fail with a clear message instead of dialing someone's home network.
• The Juice GPU-over-IP shim. Both model services shipped a juice-entrypoint.sh that LD_PRELOADed a remote-GPU libcuda.so (plus the libatomic1 package it needed). Removed entirely — the services keep their existing built-in CUDA-detect / OOM→CPU fallback and just run python app.py.
• The hard LiteLLM coupling. Text/document generation now activates only when LITELLM_URL is set (any OpenAI-compatible endpoint; a new LITELLM_MODEL override handles endpoints without the personal gateway's model aliases). No LLM gateway container is bundled.
• Identifying strings in the AssetForge README: a LAN IP, a Tailscale hostname, home-server storage paths (/mnt/...), and "built for " wording → localhost URLs, container paths, neutral wording. GPU-node labels → neutral. Comments referencing "this homeserver" → generic.
• No runtime data ships. Fresh named volumes; the app boots with an empty job list, and the model caches download on first use.
• Family data was never at risk here — the studio's story-generator and TTS-history databases (which do contain family names) belong to services that are not part of this clone (see below).

Bugs found and fixed during cloning (faithful, minimal fixes)

1. Stale TripoSR test — the shipped test mocked the TripoSR wrapper returning raw GLB bytes, but the pipeline had since moved to a JSON {mesh_url} + separate-download contract, so the test failed against the code next to it. The mock now matches the real contract (verified: 3/3 tests pass).
2. README port drift — the original README's architecture diagram and access URLs said :8211; the service has always listened on :8212. Corrected (the README is user-facing — it renders in-app on the Docs page).

Known limitations (stated honestly)

• Personal-LAN tool: no authentication on any endpoint, and Socket.IO CORS is *. Put it behind a reverse proxy with auth before exposing it.
• One job at a time, by design. The queue is deliberately single-concurrency (the original shared one small GPU/CPU budget). Also, the in-memory queue does not survive restarts: jobs stuck running are marked failed at startup, and pending rows are not re-enqueued — the original's "no jobs are lost" comment overstates it.
• CPU generation is slow. MusicGen: ~4–5 min per 30 s clip (clips clamp to 5–30 s; short clips are the sane default). Shap-E: ~5–7 min per GIF at minimum settings (CPU-dependent), more at the UI defaults. These are real model inference times, not bugs.
• The image pipeline needs a key. There is no key-free image backend — without HF_TOKEN/OPENAI_API_KEY/COMFYUI_URL, image jobs fail with a clear message. Note the hf-sd15 menu entry actually maps to SDXL (HF delisted SD 1.5 upstream; the original absorbed that).
• 4 of the studio's 7 services are not cloned, deliberately:
• AI Playground (19-task ML playground, ~130 curated models) — key-free it reduces to dashboards and avatar generation; nearly every interesting task needs HF/LLM credentials, so a clone would demo mostly empty.
• TTS Studio and StoryForge (voice browser; family story generator) — their cores require an LLM/TTS stack, and their histories/databases carry family data. Cleanest de-identification was to not ship them.
• ACE-Step (full-quality music with lyrics) — a ~5 GB model download and a heavyweight patched build for minutes-long CPU generations; too heavy for a reasonable demo clone. Its backend entry remains and works if you point ACE_STEP_URL at your own instance.
• A hidden bark audio backend exists in the pipeline (not in the UI) for a Gradio tts-generation-webui — kept as-is, off unless TTS_GEN_URL is set.
• The containers run as root (as the original did); hardening is left to the deployer.