System overview
Vork is a headless 3D and VFX engine for AI agents. An agent writes a scene, renders it, inspects the image, then adjusts the camera, materials or lights through the CLI and scene files.
The engine is written in Rust and Slang and uses Vulkan or Metal. Ordinary scenes can use JSON directly or generate it through the TypeScript or Python SDK; custom GPU programs can extend materials, cameras, compute and compositing.
Scene authoring
- JSON
- TypeScript SDK
- Python SDK
CLI validation and rendering
- Scene checks
- Render profiles
- GPU execution
Output acceptance
- Images and video
- Control channels
- Warnings and completion metadata
Inspect the image and warnings, then revise the scene program.
Use cases include procedural product shots, scene variations, animation and composites with live-action footage. The project is a research preview with approximate default lighting; test the appearance and stability of arbitrary Blender scenes individually.
The source version is 0.5.1, pinned to commit 5de38c2f81edd6d3c1c19bb1ed5bb90547856301. This research did not run GPU renders of the examples. Performance figures come from official records; the EEVEE bird comparisons are projections.
Installation and verification
| Platform | Confirmed requirements | Video dependencies |
|---|---|---|
| macOS | Apple Silicon, macOS 26 or later and Metal; the installer rejects older systems | MP4 uses system VideoToolbox; decoding and some fallbacks need ffmpeg |
| Linux | x64, glibc 2.35 or later, GLIBCXX_3.4.30 and an NVIDIA Vulkan driver with hardware ray tracing | MP4 muxing needs ffmpeg |
| Windows | x64 Windows 10/11 and an NVIDIA Vulkan driver with hardware ray tracing | MP4/MOV needs ffmpeg |
- Not completed:
Confirm that the GPU supports ray queries; AMD and Intel GPUs and Intel Macs are unsupported.
- Not completed:
NVIDIA A100, H100, H200, B200 and B300 lack the required hardware ray tracing. GPU age alone does not establish compatibility.
- Not completed:
TypeScript authoring needs Node 22.18 or later and npm; Python authoring needs Python 3.11 or later. Direct JSON authoring does not need these language runtimes.
- Not completed:
Keep the complete installation directory. Slang, OIDN, libraries, SDKs and license files beside the executable are part of the package.
macOS and Linux installer
Install the NVIDIA driver first on Linux. These Ubuntu dependency commands require administrator privileges.
sudo apt-get update
sudo apt-get install -y ca-certificates curl tar libvulkan1 libgomp1 ffmpegmacOS and Linux use the same official installer. Download and inspect the script before running it; it verifies SHA256SUMS, installs in the user directory, runs setup and updates the shell PATH.
curl -fL https://github.com/voyager-so/vork/releases/latest/download/install.sh -o /tmp/vork-install.sh
sh /tmp/vork-install.sh
export PATH="$HOME/.local/bin:$PATH"
vork --version
vork helpWindows installer
Install the NVIDIA driver and ffmpeg. After using winget install Gyan.FFmpeg, open a new PowerShell window and run the official installer.
$installer = Join-Path $env:TEMP 'vork-install.ps1'
Invoke-WebRequest -UseBasicParsing https://github.com/voyager-so/vork/releases/latest/download/install.ps1 -OutFile $installer
powershell -NoProfile -ExecutionPolicy Bypass -File $installer
$env:Path = "$env:LOCALAPPDATA\Programs\vork;$env:Path"
vork --version
vork helpnpm project installation
With Node 22.18 or later and a supported GPU, you can install Vork in a project. Keep npm optional dependencies enabled; they provide the platform runtime packages.
npm create vork@latest my-shot
cd my-shot
npx vork setup
npx vork render scene.json --out render.pngWith an npm project installation, prefix all subsequent vork commands with npx and run them from the project directory.
For an existing npm project, use npm install @voyager-so/vork. The unscoped npm package vork is unrelated; the root README labels pip support as coming soon, while the Python package README documents a pip SDK. The Python instructions below use the SDK in the complete installation package; the pip SDK itself does not include the renderer.
First image and SDKs
After using the complete installer, create a starter project with bundled geometry only. vork init needs neither network access nor a GPU and refuses to create output files that would overwrite existing ones.
vork init my-shot
cd my-shot
vork check scene.json --profile std/previs
vork render scene.json --profile std/previs --out preview.png
vork render scene.json --profile std/final --out final.pngOpen preview.png to inspect the framing, then change a color or camera position in scene.json. A successful vork check prints Scene checked successfully, but does not test GPU memory capacity or the encoder.
| Authoring option | Creation command | After editing |
|---|---|---|
| JSON | vork init my-shot | Render scene.json directly |
| TypeScript | vork init my-ts-shot --language typescript | Install the SDK as the starter README instructs, then run node scene.ts to regenerate JSON |
| Python | vork init my-py-shot --language python | Install the SDK in a virtual environment, then run python scene.py to regenerate JSON |
The complete installer provides these macOS/Linux SDK paths. Run the commands in your project and keep the native vork executable on PATH.
python3 -m venv .venv
. .venv/bin/activate
python -m pip install "$HOME/.local/lib/vork/python"
npm install "$HOME/.local/lib/vork/sdk"On Windows, the SDKs are in %LOCALAPPDATA%\Programs\vork\python and %LOCALAPPDATA%\Programs\vork\sdk; run Python source with .venv\Scripts\python scene.py. Use the SDK and engine from the same release; VORK_BIN selects an executable.
Core capabilities
Scene
vork help nodes --all
Geometry and assets
Use built-in shapes, meshes and glTF assets. Scenes use right-handed coordinates with Y up and distances in meters; asset paths resolve relative to the scene file.
Appearance
vork help materials --all
Materials and lights
Start with built-in OpenPBR inputs for ordinary materials and write Slang for custom appearances. An RGB background changes what the camera sees without illuminating the scene.
Animation
vork help animation --all
Tracks and timing
Animation layers can contain tracks or a glTF clip, with STEP, LINEAR and CUBICSPLINE interpolation. Topology and program code remain fixed during rendering; camera target cannot be animated directly, but can refer to a named node with a translation track.
Extension
vork help programs --all
Slang and simulation
Public interfaces cover surfaces, displacement, cameras, environments, compositing and compute. Simulation uses fixed time steps and can replay from initialization or compatible checkpoints; complex programs increase first-use compilation time.
Default rendering combines raster visibility with hardware ray-traced lighting; path tracing is also available. The CPU still handles scene parsing, animation-track evaluation and file IO, so GPU compute does not put all work on the GPU.
Render profiles
| Profile | Default samples | Use | Main limitation |
|---|---|---|---|
std/previs | Depends on the preview strategy | Framing, materials and direct lighting | Omits indirect bounce lighting; unsuitable for judging final lighting |
std/draft | 4 | Lighting previews | Approximate indirect lighting with OIDN denoising by default |
std/final | 8 | Default delivery | Approximate indirect lighting omits some bounce paths |
std/path | 64 | Interiors, glass and caustics | Finite bounce and sampling budgets; usually slower |
Use --set samples=32 to override sampling; the allowed range is 1 to 4096. More samples cannot restore light-transport paths omitted by std/final. Compare with std/path when interiors look too dark or glossy bounces differ from the expected result.
Without a fast GPU denoiser, draft and final switch to 16 and 32 samples without denoising. --set denoise=true forces the slower CPU denoiser; --set denoise=false disables denoising.
vork setup warms only the starter scene at std/final; ordinary GPU shader warmup has a ten-minute limit and may end successfully with the remaining compilation deferred. Failed required GPU or tool checks still report errors; vork setup --skip-warmup performs required checks only, and vork setup --all warms the built-in program and profile catalog without that limit. CPU-mode warmup also has no time limit, and new scene programs can still take minutes to compile on first use.
Outputs and completion checks
| Output | Naming | Acceptance condition |
|---|---|---|
| PNG still | --out preview.png | Defaults to the starting time; preserves alpha |
| PNG sequence | --out frames/ | Use a directory; PNG numbered filename patterns are unsupported |
| OpenEXR sequence | --out frames/%06d.exr | Multilayer, scene-linear and premultiplied alpha; stills also require the numbered pattern |
| H.264 MP4 | --out clip.mp4 | Final alpha must be opaque in every composited frame |
| ProRes 4444 MOV | --out clip.mov | Preserves final alpha; encoding depends on the platform |
--channels accepts color, depth, object_index, view_normal, motion, camera, shadow_catcher and aov:NAME. Some PNG control channels quantize or clamp values. Use EXR for scene-linear floating-point data and interpret each channel as documented in vork help outputs.
Directory outputs use meta.json; file outputs use a sidecar such as clip.mp4.meta.json. Video also writes camera metadata, and --diagnostics adds timing records.
Agent operating practices
Separate scene content from quality
Inspect framing with previs, then compare lighting with final or path. Record the scene, profile and output path; a low-quality preview is insufficient for delivery acceptance.
Check before rendering
Run check with the same profile as the intended render; add --shaders for portable shader compilation checks. check does not open a GPU but still needs the matching Slang toolchain.
Preserve external resources together
The SDK can externalize large data into buffers and remove obsolete generated files referenced by the previous JSON when saving. A snapshot needs the JSON and all referenced resources; serialize saves and reads at one destination.
Inspect images and warnings together
A successful render can omit or substitute effects. Include stderr, completion metadata, warnings and the image in acceptance checks, then decide whether the omitted effects require revision or rejection.
Give an agent the subject, shot, output and acceptance conditions. The official README starts with creating a starter scene, reading vork help, rendering and inspecting a preview, then confirming the camera and lighting before final-quality output.
Rounded-box example
Save this scene from the official README as scene.json. It uses bundled geometry and needs no external model downloads; the image contains a blue rounded box, a floor, an area light and a camera.
{"version":2,"nodes":[
{"type":"mesh","geometry":{"std":"rounded_box","size":[2,2,2],"radius":0.3},
"materials":[{"inputs":{"base_color":[0.12,0.35,0.65],"specular_roughness":0.3}}]},
{"type":"mesh","translation":[0,-1.1,0],"geometry":{"std":"rounded_box","size":[10,0.2,10],"radius":0},
"materials":[{"inputs":{"base_color":[0.35,0.35,0.35]}}]},
{"type":"light","shape":"rectangle","translation":[-3,5,4],"target":[0,0,0],
"energy":700,"size":4,"color":[1,0.92,0.8]},
{"type":"camera","translation":[3,2,5],"target":[0,0,0]}
],"render":{"resolution":[640,480]}}Check the scene and render stills before testing video output.
vork check scene.json --profile std/previs
vork render scene.json --profile std/previs --out preview.png
vork check scene.json --profile std/final
vork render scene.json --profile std/final --out final.png
vork render scene.json --profile std/final --frame-start 0 --frame-end 23 --out clip.mp4For a moving shot, add translation or rotation tracks using vork help animation --all, then inspect the beginning, middle and end. To import model.glb, use type: asset and file, keep accompanying textures and buffers together, and adjust framing for the model's scale.
Official performance figures
| Official case | Vork time | Comparison | Scope |
|---|---|---|---|
B-interior.json final movie | 59.231 seconds | EEVEE 107.026 seconds | 240 frames, 1920 × 1080, 24 fps; different sampling and quality |
B-night.json final movie | 92.201 seconds | EEVEE 213.477 seconds | Same warm movie group; not an equal-quality comparison |
| Million-bird skim | 96.942 seconds | EEVEE projection at the same 4 samples: 773.7 to 1082.5 seconds | 192 frames, 1080p; EEVEE extrapolated from a subset of frames |
B-car-pan.json path-traced still | 26.901 seconds | Cycles 4.632 seconds | Carried forward from an earlier build; Vork is slower |
The final and bird results use the project's recorded build 81ae2b075 on an NVIDIA L4; they were not remeasured at the source commit reviewed here. Bird setup and warmup take another 243.809 and 166.030 seconds, for 506.781 seconds including the movie. Asset preparation and transfers are additional.
The broader official sweep delivered 583/585 images; the million-star scene ran out of memory in both profiles. An earlier set of 19 quality comparisons failed its declared FLIP condition and was not repeated on that build. Detail, defocus and highlight differences still need visual review.
Limits and troubleshooting
| Symptom | Cause or limitation | Action |
|---|---|---|
nvidia-smi sees a GPU, but Vulkan sees only llvmpipe | The container may be unable to load the NVIDIA ICD | Check driver discovery using the official remote-GPU guide |
| A new scene takes a long time to produce its first image | New programs or pipelines need cold compilation | Read progress and retain caches; rerun setup after upgrades or driver changes |
| An interior stays dark after increasing samples | final omits some light-transport paths | Compare with path and inspect materials and lights |
| Glass or dense transparency aborts on Mac | Known Metal reliability limits | Try path or a supported NVIDIA GPU and test the complete shot; lowering resolution is not a guaranteed fix |
| A shot needs smoke or varying volume density | Arbitrary smoke, grid density and some custom combinations are unsupported | Use homogeneous media or qualified height fog under the fog rules, or composite other effects separately |
| Output succeeds but an effect looks wrong | Some effects are omitted or substituted with a warning | Inspect stderr and warnings; exit status alone is insufficient |
On Linux, explicitly select vork setup --gpu cpu and vork render scene.json --gpu cpu --out frame.png. The Mesa Vulkan driver still needs ray queries and storage buffer arrays. CPU rendering is slow and never selected automatically; Metal has no corresponding CPU mode.
| Exit code | Category | Next action |
|---|---|---|
| 0 | Success | Inspect fresh metadata, warnings and the image |
| 2 | Usage error | Check the command, flags and output naming |
| 3 | Invalid scene or program | Fix the schema, resources or Slang program |
| 4 | Device, GPU memory, encoder or setup | Adjust resources or the environment according to the specific error |
| 5 | Filesystem IO | Check paths, permissions and available storage |
A refused frame stops a movie. PNG/EXR sequences can continue through other frames but still exit unsuccessfully and do not write completion meta.json. Preserve exit status in batch workflows.
Licensing and asset management
Vork uses LicenseRef-vork-Preview, provides source code and permits free commercial use during the research preview. This is not an open-source license; later versions may have different terms.
| Activity | Current license conditions |
|---|---|
| Internal rendering and delivering finished media to clients | Allowed |
| Modifications for your own use | Allowed |
| Sharing unmodified copies | Keep the license and all notices |
| Distributing modified versions, selling or relicensing Vork | Prior written permission required |
| Hosting a rendering service where others submit scenes or jobs | Prior written permission required |
Vork claims no rights in the scenes, code or media you create; imported assets keep their own terms. The Blender bridge is a separate GPL-3.0-or-later component. Example images, models and footage have separate licenses; retain their required credits.
Vork checks npm for stable-version updates at most once per day and displays a later notice on stderr. Set VORK_NO_UPDATE_NOTIFIER to disable this; it affects update checks and notices only.
Next steps
Verify a still made with built-in geometry before adding your own glTF model; first fix the camera, resource paths and output specification.
Build downstream handling for depth, normals, object indices and camera data using
vork help outputs, and retain completion metadata.In a source checkout, read the preparation steps and licenses in
examples/cake/,examples/vfx-artifact/andexamples/murmuration/before using their assets.Import Blender scenes with the bridge's headless command and inspect substitutions and omissions in
export-report.json; its OpenPBR translation does not guarantee the same appearance as Blender.
blender -b --disable-autoexec source.blend --python integrations/blender/export.py -- --out /tmp/vork-sceneWithout a suitable local GPU, you can evaluate Voyager's official cloud rendering. This manual has not verified its account requirements, pricing or quotas. Confirm the Preview License's written-permission requirements before offering your own hosted service to multiple users.