Vivijure Local
Self-hosted Vivijure Studio for homelab and hobbyist builders -- Node, SQLite, and
S3-compatible storage, no Cloudflare account required. Full capability parity with
vivijure-cf: same modular film-studio API,
same vivijure-module/2 contract, same public/ UI, different runtime. Default path is
Ollama plan.enhance → unload → local-gpu keyframe (16GB door first) → CPU finish. The default
compose stack registers no RunPod modules
(local#265,
local#200).
For production workloads (Cloudflare Workers, R2, AI Gateway), use
vivijure-cf.
Both hosts share vivijure-core. Drive either
host from an agent with vivijure-mcp.
Constellation map: vivijure.
Dependency pins: see package.json and the lock file for the @skyphusion-labs/vivijure-core
and @skyphusion-labs/vivijure-mcp versions. Product
capability parity with vivijure-cf is the dual-panel release-wave gate; package floors can lag
the CF host.
Provider-neutral host for Vivijure Studio: same reference API
(CONTRACT.md).
GPU render backends (vivijure-local-16gb first, vivijure-local-12gb alternate, finish sidecars)
plug in via module URLs; this repo is the control panel host only.
Local vs Cloudflare (vivijure-cf)
| vivijure-local (this repo) | vivijure-cf (production) |
|---|
| Who | Homelab / hobbyist self-host | Cloudflare-hosted studio |
| Runtime | Node + Docker + MinIO + Ollama | Workers + D1 + R2 |
| Contract | Full parity (CONTRACT.md, module registry) | Same |
| GPU default | Ollama + 16GB local door + CPU finish | Cloud motion doors; SDXL keyframes and upscale on RunPod |
| RunPod | Opt-in only (COMPOSE_PROFILES=cloud / satellites) | Keyframes and upscale; motion through cloud doors or your own GPU |
| When to pick | Your box, LAN you control, own GPU | Production, free-tier CF stack, no homelab ops |
Route checklist: docs/PARITY.md. Homelab operator path: docs/quickstart.md.
CF path: vivijure-cf quickstart.
Rendering without RunPod (the default)
You never need a RunPod account. A complete film renders with zero RunPod modules in the default
compose stack:
- Planning (
plan.enhance) runs on local Ollama (default qwen3:14b, ~9.3GB Q4 on a
16GB card); the model is unloaded before keyframe work claims the GPU.
- Motion and keyframes render on your own GPU through the local door
(
vivijure-local-16gb first;
vivijure-local-12gb alternate); set
LOCAL_BACKEND_URL and run npm run install:studio.
- Optional CF AI overlays (dialogue / music / narration) when you add gateway creds; not required
for the Ollama + door path.
- Finish runs on the CPU
video-finish container (assemble and mux), plus optional local
lipsync / upscale sidecars.
A GPU engine is required to render. Compose brings the rest of the stack up without one: the door
module lives in the localgpu profile, so with no door it is simply not in the stack -- nothing to
hide, nothing to refuse. GET /api/modules then reports keyframe and motion.backend as
unavailable with the knob named, so the panel greys those controls out before a render is spent.
Nothing is rendered with placeholder frames (see
local#229,
local#280).
Set PLANNER_AI_MOCK=true if you skip the Ollama model pull.
Optional: wire RunPod via COMPOSE_PROFILES=cloud (or satellites) for cloud i2v, RunPod
keyframe, MiniMax HD narration, RunPod finish. Strictly opt-in. Wiring guide:
docs/DEPLOYMENT.md.
Who this is for
Homelab and hobbyist builders who want the full Vivijure studio on their own box: module registry,
render orchestrator, local GPU door, and local finish sidecars, all on Node/Docker without a
Cloudflare account. Same single-operator trust model as the CF host; keep it on a network you
control (see docs/SECURITY.md).
Production / Cloudflare: vivijure-cf · Homelab path: docs/quickstart.md
Vivijure Studio: https://vivijure.dev · Skyphusion Labs: https://skyphusion.org
Quick start
git clone https://github.com/skyphusion-labs/vivijure-local
cd vivijure-local
npm ci # install the tools install:studio runs (tsx)
npm run install:studio # mint token + seed platform_secrets
npm run compose:up # docker compose pull (GHCR :latest unless VJ_IMAGE_TAG is set) + up -d
curl -fsS http://127.0.0.1:8790/health
Open http://127.0.0.1:8790 and paste the token from .studio-token. The friendly walk-through is
docs/quickstart.md; the full operator reference is
docs/DEPLOYMENT.md.
Verify the render pipeline:
npm run smoke:exit # bundle -> render -> poll -> artifact
Where this fits: the constellation
Vivijure is a small group of repos that work together. The Studio control plane sits in the
center. This repo is an alternate host for that same control plane (Node/Docker instead of
Cloudflare Workers). The full map is in docs/constellation.md.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
