Grok Studio

Self-hosted image-to-video studio for Grok and MuleRouter's Wan 2.7 Spicy. Your provider credentials stay on the server; turn an image into video from a web UI or the CLI, with outputs stored on disk. Built for local / LAN use.

Install & run

npx grok-studio

That's it. First run opens the xAI browser login if needed, then serves on http://127.0.0.1:8787. (npm i -g grok-studio also works.)

CLI

grok-studio serve [--provider grok|wan-spicy] [--open]  # start the web app
grok-studio gen --image a.png --prompt "slow head turn" \
  [--prep --duration 6 --resolution 720p --aspect 9:16 --count 2 --out clip.mp4]
grok-studio gen --provider wan-spicy --image a.png --prompt "slow head turn" \
  [--negative-prompt "flicker" --duration 5 --resolution 1080p --seed 42]
grok-studio login            # xAI OAuth login (browser)
grok-studio status           # config + xAI auth + server health

Interactive startup asks whether to use Wan 2.7 Spicy or Grok. For scripts and other non-interactive launches, pass --provider or set DEFAULT_VIDEO_PROVIDER. If Wan is selected without MULEROUTER_API_KEY, an interactive terminal securely prompts for a key for that run.

gen is headless: image →(optional --prep first frame)→ video, no UI; result paths print to stdout.

Web UI

• Left rail — + adds a source image; Active Jobs lists running work globally; Outputs is a gallery of every Frame / Video.
• Result Graph (center) — every node is one concrete run: Source → Frame (each prep) → Video (each run). Forks are sibling nodes. Lineage is derived purely from data (inputFrame.preparedImageId / clientSourceId), never guessed from history.
• Inspector (right) — the only place to view a result, download, rerun, prep, or animate the selected node.
• Video provider — switch each video run between Grok and Wan 2.7 Spicy. Existing jobs remain compatible and default to Grok.

Configure (.env)

.env is read from the directory where grok-studio is launched. In particular, running npx grok-studio from another directory does not read a checkout's .env.

HOST=127.0.0.1                 # 0.0.0.0 for LAN access
PORT=8787
ACCESS_TOKEN=                  # set to gate non-loopback access (empty = open on loopback/LAN)
WORKSPACE_DIR=~/.grok-studio/workspace  # holds images/ videos/ jobs/ prepared-images/
DEFAULT_VIDEO_PROVIDER=grok             # or: wan-spicy
XAI_AUTH_MODE=oauth            # or: api_key (+ XAI_API_KEY)
XAI_VIDEO_MODEL=grok-imagine-video-1.5
XAI_IMAGE_MODEL=grok-imagine-image-quality
MULEROUTER_API_KEY=             # required for Wan 2.7 Spicy
# MULEROUTER_WAN_SPICY_BASE_URL=https://api.mulerouter.ai/vendors/carrothub/v1/wan2.7-i2v-spicy

Wan 2.7 Spicy supports 720p/1080p, 2–15 second clips, negative prompts, optional audio or an HTTPS MP3/WAV URL, prompt extension, and a reproducible seed. Its API key is only read by the server and is never sent to the browser.

Develop

vp install
vpr check && vp test && vpr build && vpr smoke

Quality gates: React/a11y lint, type checks, an architecture-size test (tests/architecture.test.ts), and a Playwright smoke (scripts/smoke.mjs).