English | 中文
Cuti Harness is a general-purpose, open-source, plugin-based video harness for long-horizon video creation built on DeepSeek Harness. The harness owns the conversation, agent loop, and high-level tool selection. The video Runtime owns durable projects, Skills, artifact dependencies, incremental builds, timelines, validation, and exports.
This repository includes the Cuti Harness agent algorithm and loop, the Video Runtime backend, the Video Studio frontend, a compatibility BFF, Media Service, Sandbox Worker, and the provider, workflow, validator, and media plugins they use.
Two real exports from Video Studio: iterative world building in conversation, and a fully automated one-shot long video from a single brief. GIF previews loop short clips; long exports may be sped up for GitHub playback.
Five conversation turns grow one cinematic clip from 15 seconds to 3 minutes. Later turns extend the same timeline instead of starting over. Each GIF loops a short clip from that turn; turn 5 is a sped-up view of the 3-minute export.
Glass Tide Reference: Inception - Folded City + Doctor Strange - Kaleidoscope Photoreal city avenue at blue hour. A ten-story wave of liquid glass rolls down the street towards the camera, reflecting the skyline, then freezes mid-twist into a translucent structure. Camera: slow push-in, 35mm anamorphic, wet asphalt, neon in the glass. No close-ups of people, no text, no logos. IMAX, film grain, 16:9.
Make a 30-second video with continuous shots. It should be dynamic, more eye-catching and faster.
Continue for another 15 seconds, and add a beautiful angel flying in.
Generate another 15 seconds of video. Use the last frame of the previous video as the first frame. The camera follows this angel, then flies forward, and a heaven appears.
Continue generating. This angel flies through prehistoric, ancient, early-modern, and contemporary eras. Export a 3-minute version.
For easier playback, the preview GIF is sped up from the full 3-minute export.
From one cinematic brief (After the Rain), Cuti Harness plans shots, runs generation, and assembles a complete ~5-minute trailer with no manual timeline edits between steps. The workflow is fully automated end to end.
For easier playback, the preview GIF is sped up from the full ~5-minute export.
More demos: see the Cuti Harness webpage.
See Cuti Harness architecture.
This is the release acceptance path for the open-source branch. The setup command prepares dependencies, and the start command runs Video Studio, Cuti Harness, Video Runtime, Media Service, and Sandbox Worker. Docker, PostgreSQL, and Redis are not required.
- Git.
- Node.js
22.19+or24+. - pnpm
11.x. Runpnpm --version; if pnpm is missing, runcorepack enable. - Conda (Miniconda, Miniforge, or Anaconda).
- Internet access during environment setup so the setup command can install Python packages and separately licensed FFmpeg/FFprobe tools.
git clone https://github.com/VideoVerses/Cuti-Harness.git
cd Cuti-HarnessThe repository has one branch, main, which Git checks out automatically.
Run from the repository root:
conda env create --file environment.yml
conda activate cuti-video-agentIf the environment already exists, run:
conda env update --file environment.yml --prune
conda activate cuti-video-agentRun every subsequent command with the cuti-video-agent environment activated.
Run from the repository root:
pnpm install --frozen-lockfile
pnpm run buildThe root build also produces the Video Studio bundle required by the local launcher.
Copy the configuration template from the repository root. On macOS or Linux:
cp config/.env.example .envOn Windows PowerShell:
Copy-Item config/.env.example .envOpen the new repository-root .env in a text editor and replace the values after each equals sign with your real keys:
OPENAI_API_KEY=sk-your-real-openai-key
WAVESPEED_API_KEY=your-real-wavespeed-keyOPENAI_API_KEY powers the Harness conversation and planning model, while WAVESPEED_API_KEY powers the default Seedance video path. When WAVESPEED_API_KEY is empty, new projects default to the local Code-to-Video mode; the dedicated composer button can enable or disable it for each project. To use Volcengine Ark instead, leave WAVESPEED_API_KEY empty, set ARK_API_KEY, and disable Code-to-Video when you want the provider workflow. SUNO_API_KEY is needed only for music generation. Restart the local stack after changing a key so it is reloaded.
Keep the cuti-video-agent Conda environment activated, then run:
pnpm video:setup -- --data-dir .video-agent-harness-dataThe Conda definition owns the environment name, Python 3.11, and pip. The setup command verifies that this exact Conda environment is active, installs the pinned Python service dependencies into it, and installs FFmpeg/FFprobe plus the pinned HyperFrames renderer under .video-agent-harness-data. It does not start any service. Run it again after the Python requirements or local renderer version changes, or when using a new data directory.
To let setup download a checksum-verified portable Python instead of using an existing Python environment, pass --portable-python. This is an explicit alternative, not the default:
pnpm video:setup -- --portable-python --data-dir .video-agent-harness-dataKeep the cuti-video-agent Conda environment activated, then run:
pnpm video:local -- --data-dir .video-agent-harness-dataThe start command only checks the prepared environment and starts services; it does not download Python or install dependencies. Keep this terminal open. The repository-local data directory is ignored by Git and avoids cross-volume rename errors on some Windows installations.
When using the optional portable environment, pass the same option to start:
pnpm video:local -- --portable-python --data-dir .video-agent-harness-dataWhen the terminal prints Cuti Harness is ready, open http://127.0.0.1:3000/#/zh/create. Video Studio has no login flow; local project identity is local-user.
In a second terminal, run conda activate cuti-video-agent, then run from the repository root:
pnpm video:doctor -- --data-dir .video-agent-harness-data
curl http://127.0.0.1:8001/healthDoctor should report every component, including Local HyperFrames renderer, as OK; the health response should be {"status":"healthy"}. Port 3000 is Video Studio, 3080 is Cuti Harness, 8001 is Video Runtime, 8700 is Sandbox Worker, and 18080 is Media Service.
Portable-environment users also pass --portable-python to video:doctor.
Stop the stack with Ctrl+C in its terminal. Local npm mode is intended for a trusted single-user machine: its subprocess worker is not a security isolation boundary. Use Docker Compose deployment for PostgreSQL, multi-user operation, or untrusted executable plugins.
Try a low-cost first prompt such as:
Create a 10-second, two-shot cinematic video of a robot watering one flower at sunrise. Use the same robot in both shots, no narration, and export the final MP4.
Tool configuration sources live in config/root/. pnpm install generates the Git-ignored root entrypoints required by TypeScript, editors, tests, and Git hooks. Edit the source files there, and run node scripts/materialize-root-configs.mjs after pulling configuration updates or when installing with --ignore-scripts.
To run Video Studio with Vite hot reload, keep the complete local stack running, then use another terminal:
cd apps/video-studio
cp ../../config/.env.example .env.localSet these values in apps/video-studio/.env.local:
VITE_VIDEO_RUNTIME_URL=http://127.0.0.1:8001
VITE_VIDEOCHAT_URL=http://127.0.0.1:8001
VITE_CUTI_BACKEND_URL=http://127.0.0.1:8001
VITE_BACKEND_URL=http://127.0.0.1:8001Studio has no login flow. Project identity is local-user in Video Runtime.
Return to the repository root and start Vite:
pnpm --filter @cuti-ai/video-studio run devOpen http://127.0.0.1:5173/#/zh/create.
| Symptom | Check |
|---|---|
| The UI opens but sending a prompt has no response | Confirm Cuti Harness is still running on port 3080 and OPENAI_API_KEY is present in the repository .env. |
401, NO_AUTH, or model authentication error |
Check OPENAI_API_KEY in .env, then restart the local stack so the launcher reloads it. |
| Video or image generation fails | Configure the provider key required by the selected workflow; the default Seedance path needs WAVESPEED_API_KEY or ARK_API_KEY. |
| Build remains queued or the Runtime is unavailable | Run pnpm video:doctor -- --data-dir .video-agent-harness-data and inspect the launcher terminal. |
| Port is already in use | Free or remap ports 3000, 3080, 8001, 8700, or 18080. Keep URLs and proxy settings consistent. |
EXDEV or cross-device appears during first-run installation |
Use the documented --data-dir .video-agent-harness-data command and do not point the data directory at another drive. |
| Model, provider, or first-run dependency download times out behind a proxy | Export HTTP_PROXY, HTTPS_PROXY, and NODE_USE_ENV_PROXY=1 in the launching shell, not in .env, then restart the stack. The launcher detects an enabled Windows user proxy automatically. |
pnpm --filter @cuti-ai/video-studio run build
python -m unittest discover -s services/video-runtime/tests/video_runtime -vThe repository also retains the broader DeepSeek Harness checks. See development and contributing.
This project is in developer preview and can introduce compatibility-breaking changes. Provider calls may incur real costs. Start with short videos and low-cost test prompts.
- Project Lead: Yingqing He
- Core Contributors: Kai Sun, Songsong Wang, Pengjun Fang
- Co-Lead: Yazhou Xing
This project is licensed under the MIT License. DeepSeek and imported Cuti provenance is documented in Source Provenance. Third-party dependencies and licenses are listed in THIRD_PARTY_NOTICES.md.