# Agent quickstart — install to first render For an AI agent on a machine that has never run videoclaw, told "install this and make me a video". Follow it top to bottom. The §4 sequence was run end to end on a clean prefix install and produced a real clip for 0 credits; the two commands this release adds (`vclaw --version` and `assets --text-only`) stand in for the workarounds that run needed. Two surfaces are more current than any prose, including this page: `vclaw schema --json` is the authoritative command index (every registered command with its usage string and flags), and `skills/catalog.json` is the skill index. Read both once at the start of a session and drive from them. ## 1. Install and prove it ```bash npm install -g videoclaw@alpha vclaw --version vclaw video providers ``` `vclaw --version` (or `-v`) prints the bare version string and exits 0 — the same value `vclaw schema --json` carries as `version`, and the one command whose output is plain text rather than JSON. `video providers` needs no credentials and submits nothing; it prints every route with its `availability`, its missing env vars, and copy-pasteable fix text for anything it can name. ### Local vocal guides for lip-sync uploads When asked to alter a vocal **only to drive lip sync**, process the existing stem; do not generate new lyrics or a new song performance. Use: ```bash vclaw video vocal-guides --input /path/to/vocal-stem.wav vclaw video vocal-guides --project my-film --windows w00,w01 --root /path/to/workspace ``` This free local command exports a 150 Hz flat guide and a +4-semitone guide as 320 kbps MP3s, retaining the original articulation and decoded duration. It leaves the source and upload references unchanged and does not upload anything. Project batch export requires an existing stem-based plan; use the command directly for old projects rather than restarting production. For dependency setup, safe reruns, and automatic planning exports (`VOICE_SOURCE=stem`, `VOICE_GUIDES=1`), read [the rap-video agent skill](https://github.com/davendra/videoclaw-v3/blob/main/skills/rap-avatar-mv/SKILL.md#export-vocal-guides-for-manual-uploads). ## 2. Where the keys go Keys belong in your shell (`export NAME=value`) or in `$VCLAW_WORKSPACE/.env.local` — the file `video providers`, `verify-env` and the native provider transports read. **Never put keys inside the installed package**: `npm update` deletes that directory. The workspace root resolves as `--root` flag, then `VCLAW_WORKSPACE`, then `VIDEOCLAW_WORKSPACE`, then `~/videoclaw`. | Route | Env vars | Renders free? | |---|---|---| | `veo-useapi` | `USEAPI_API_TOKEN`, `USEAPI_ACCOUNT_EMAIL` | **Yes** — `--veo-model free` selects `veo-3.1-lite-low-priority` at 0 credits. Provider-gated to Ultra-tier accounts; it errors clearly on others. | | `seedance-direct` | `SUTUI_API_KEY` (paid xskill.ai transport) | **Yes**, without a key — bootstrap the in-tree Higgsfield engine (§3). | | `runway-useapi` | `USEAPI_API_TOKEN`, `USEAPI_ACCOUNT_EMAIL` | Explore mode is free in principle, but this project has had no Runway account since 2026-08-10. The route stays registered; do not plan work on it. | | `dreamina-useapi` | `USEAPI_API_TOKEN`, `VCLAW_DREAMINA_ACCOUNT` (e.g. `CA:you@example.com`) | No. | | `magnific-rest` | `MAGNIFIC_API_KEY` | No — a paid image/video finishing backend. | | `reapi-seedance` | `VCLAW_REAPI_SEEDANCE_VIA=treg` + `TREG_TOKEN`, or `=direct` + `REAPI_API_KEY` + `GO_BANANAS_API_KEY` | No — Seedance 2.5 with the content filter off (a real photograph + a voice clip in one render), paid per second of output. Opt-in only. | | `seedance-modelark` | `ARK_API_KEY` (optional: `VCLAW_MODELARK_MODEL`, `VCLAW_MODELARK_BASE_URL`, `VCLAW_MODELARK_CHAIN_MODE`) | No — the official Seedance 2.5 API on BytePlus ModelArk, billed per second of output to your BytePlus account (~USD 0.93 for 4 s at 720p). | You only need the keys for the route you intend to use. Every other route reading `unavailable` is expected and harmless. ## 3. Optional sidecars **Flow sidecar (needed for `veo-useapi`).** On a global install, copy the bundled `vclaw-cli` somewhere writable first. `npm root -g` is wrong whenever a `--prefix` was used, so ask npm for the package itself: ```bash # pass the same --prefix you installed with, if any package_dir="$(npm ls -g --parseable --depth 0 videoclaw)" flow_sidecar_dir="$HOME/.local/share/videoclaw/flow-sidecar" mkdir -p "$(dirname "$flow_sidecar_dir")" cp -R "$package_dir/vclaw-cli" "$flow_sidecar_dir" bun install --cwd "$flow_sidecar_dir" --frozen-lockfile export VCLAW_VEO_CLI_ROOT="$flow_sidecar_dir" ``` `vclaw video providers` prints that same directory in the `veo-useapi` issue text, however you installed. **Seedance 2.0 for free, through your Higgsfield account.** From `$package_dir/engines/seedance-direct`, per [its README](https://github.com/davendra/videoclaw-v3/blob/main/engines/seedance-direct/README.md): ```bash export HIGGS_VCLAW_PROFILE="$HOME/.local/share/videoclaw/higgsfield-session" ./bootstrap.sh # Python environment + Chromium ./.venv/bin/python bootstrap/find_cookies.py # find your Chrome profile ./.venv/bin/python bootstrap/import_cookies.py # import the Higgsfield session ``` Keep that variable set for every later `vclaw` run: the free engine is chosen only from *that* session path, so a session the render shell cannot see falls back to the paid API in silence. Unset, `bootstrap.sh` writes both the Python environment and the session **inside the installed package**, where they need write access and are lost on `npm update`. `import_cookies.py` also leaves a screenshot of the signed-in page; delete it. The free engine renders **one video at a time** — two runs at once get in each other's way. `bootstrap.sh` alone does not turn free rendering on. Only `import_cookies.py` proves you are signed in, so only it writes the readiness file `/.vclaw-engine-ready.json`, and the free engine is chosen only when that file reads `"loggedIn": true` (plus an executable `.venv/bin/python`). Files merely existing is not enough: the check used to accept the directories being there, which an empty `mkdir` satisfies, so a machine with nothing configured reported a working free engine. Confirm which way a route will render with `providers`: `activeTransport` reads `in-tree-engine` once the free Higgsfield engine is set up, `custom-adapter` under a `VCLAW__ADAPTER` override, and otherwise the route's built-in paid one. On `seedance-direct` there is a fourth answer, `blocked`: the free engine is not usable and nobody has asked for the paid API, so the route refuses to render rather than billing a transport you did not choose. Set `VCLAW_SEEDANCE_DIRECT_NATIVE=1` (with `SUTUI_API_KEY`) to choose it. Every route also carries `setupHint`: the next command to type when the route has issues, and `null` when it has none. On `seedance-direct` it names the setup step that has not been done and the paid alternative; on `veo-useapi` it gives the Google Flow sidecar recipe with the directory videoclaw actually resolved. A machine that already holds `SUTUI_API_KEY` has no issues when the free rendering goes dark — the route still works, it just bills — so read the route NOTES too: one of them says free rendering is off and why. ## 4. The proven zero-credit first render Free Flow, one 8-second clip, verified end to end. Substitute your own slug. ```bash vclaw video init demo vclaw video brief --project demo --title "Demo" \ --intent "An 8-second cinematic shot of an empty sunlit reading room" \ --aspect-ratio 16:9 --audio on --resolution 720p vclaw video set-execution-profile --project demo --veo-model free vclaw video storyboard --project demo --scene "Slow dolly-in across an empty sunlit reading room" vclaw video assets --project demo --text-only vclaw video produce --project demo --dry-run vclaw video produce --project demo vclaw video execute-status --project demo ``` - **`assets --text-only`** writes `{ projectSlug, assets: [], textOnly: true }`. `readiness` requires `asset-manifest` even for a text-to-video project, so without this step `produce` returns `status: "blocked"`. It also lets `plan` classify the run as `text-to-video` rather than `image-to-video`. When you do have files, pass `--asset :` instead: the two flags are mutually exclusive, the kind must be one of `image`, `video`, `audio`, `subtitle`, `other`, and a local path that does not exist is an error. - **The dry run is the contract.** It writes the resolved submit payload to `artifacts/run-contract.json` and reports that path as `contractPath`. Read the file before you drop `--dry-run`; the report printed on stdout is only a summary (`status`, `routeId`, `taskCount`). - **Plain `produce` is the live command.** There is no `--confirm-spend` gate on it; removing `--dry-run` is what makes it real. - **`produce` prints nothing for roughly two minutes. That is normal.** Calling `execute-status` from a second shell mid-flight is safe: it answers `poll.status: "pending"` with `rawResult.reason: "execution-in-flight"`, names the running pid and start time, and writes nothing. Once `produce` returns, `execute-status` polls the real job. - The clip lands at `projects/demo/outputs/scene-0.mp4`. Expect 1080p even though you asked for 720p — the free Flow lane upscales at no cost. ## 5. Which lane for which request | The request | Lane | |---|---| | Explainer or brand film | `skills/brand-explainer/SKILL.md` | | Rap or avatar music video from a portrait | `skills/rap-avatar-mv/SKILL.md` | | Kids nursery rhyme / sing-along | `rhyme-factory` | | Animated short from a story idea | `3d-animation-short` | | A scene prompt for Seedance or Flow | `ai-film-director` | | Competitor ad teardown | `ad-intel` | | Unsure, or a novice asking in plain English | `concierge` | `skills/catalog.json` is the complete lane list; this table is the common subset. Slash-command front doors are a source-checkout convenience and do not exist on a package install — read the `SKILL.md` directly. ## 5a. Plan and review a real production The first-render example is a transport smoke test. For new agent-led films, follow [Shared filmmaking workflow](SHARED_FILMMAKING_WORKFLOW.md): prepare `{filmPlan, shots}` JSON and pass `--film-plan ` alongside ordinary `storyboard --scene` and `--scene-character` arguments. Match the creative format to the task; a technical test needs observable criteria, not an invented story. Compile `filmmaking-prompts` after the plan and local references are settled. Execution refuses stale planned packets or changed local reference attachments; rebuild affected prompt evidence before rendering. This is not a guarantee that all standalone provider or batch paths consume the film plan. After assembly, inspect `review --project --film-edit `. Watch the complete export with sound and record the actual review using `--film-review --verdict pass`. Planned films need current full-playback evidence; sampled frames or technical QC alone cannot pass that gate. `publish` rechecks the reviewed media. The guide contains the complete JSON examples, supported route boundaries and legacy compatibility rules. The host agent manages phases, evidence and a saved progress page. VideoClaw's durable queue manages provider work; it does not run an internal manager agent. ## 6. This machine vs any machine Sections 1–4 require Node >=20.10 plus the chosen route’s credentials, account entitlement and optional runtimes described above. The production lanes do not: their prerequisites are **verified on the maintainer's machine only** and none of them ship with the package. - **`brand-explainer`** — FFmpeg; Python 3.12+ with Pillow importable by the system `python3`, built with RAQM text shaping; `ELEVENLABS_API_KEY` for the voiceover and Suno keys for music; Go Bananas image generation for the icon sheet; whisper to verify the voiceover. A `.brand` pack in `$VCLAW_WORKSPACE/packs/` is required and is authored, not generated. - **`rap-avatar-mv`** — FFmpeg with the full codec set; Python 3.12+; whisper (the in-tree whisper.cpp shim, or openai-whisper at roughly a hundred times the wall clock); Demucs for the vocal stem; `KIE_API_KEY` (Suno), `APIZ_API_KEY` / `XSKILL_API_KEY`, `USEAPI_API_TOKEN`, `VCLAW_VEO_CLI_ROOT`, and a logged-in Higgsfield browser profile. A `.rap.pack` is required. Treat a lane whose prerequisites you cannot satisfy as unavailable and say so, rather than substituting an improvised pipeline.