Vork field manual

Document type
Field manual
Updated
Reading time
13 min

Install and use the Vork research preview with JSON, TypeScript and Python scenes, render profiles, output channels, agent iteration, GPU limits, benchmark qualifications and commercial licensing.

Source
Document details
voyager-so/vork
License
LicenseRef-vork-Preview

Drive 3D and VFX rendering with scene programs, from the first preview to output acceptance.

Source version
0.5.1Research preview
Scene authoring options
3JSON, TypeScript, Python
Built-in profiles
4previs, draft, final, path

01Purpose and architecture

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.

Agent scene iteration
  1. Scene authoring

    • JSON
    • TypeScript SDK
    • Python SDK
  2. CLI validation and rendering

    • Scene checks
    • Render profiles
    • GPU execution
  3. 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.

02Platforms, GPUs and installation paths

Installation and verification

PlatformConfirmed requirementsVideo dependencies
macOSApple Silicon, macOS 26 or later and Metal; the installer rejects older systemsMP4 uses system VideoToolbox; decoding and some fallbacks need ffmpeg
Linuxx64, glibc 2.35 or later, GLIBCXX_3.4.30 and an NVIDIA Vulkan driver with hardware ray tracingMP4 muxing needs ffmpeg
Windowsx64 Windows 10/11 and an NVIDIA Vulkan driver with hardware ray tracingMP4/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.

bash
sudo apt-get update
sudo apt-get install -y ca-certificates curl tar libvulkan1 libgomp1 ffmpeg

macOS 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.

bash
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 help

Windows installer

Install the NVIDIA driver and ffmpeg. After using winget install Gyan.FFmpeg, open a new PowerShell window and run the official installer.

powershell
$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 help

npm 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.

bash
npm create vork@latest my-shot
cd my-shot
npx vork setup
npx vork render scene.json --out render.png

With 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.

03Creating, checking and regenerating scenes

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.

bash
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.png

Open 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 optionCreation commandAfter editing
JSONvork init my-shotRender scene.json directly
TypeScriptvork init my-ts-shot --language typescriptInstall the SDK as the starter README instructs, then run node scene.ts to regenerate JSON
Pythonvork init my-py-shot --language pythonInstall 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.

bash
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.

04Scenes, animation and GPU programs

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.

05Framing, lighting and delivery

Render profiles

ProfileDefault samplesUseMain limitation
std/previsDepends on the preview strategyFraming, materials and direct lightingOmits indirect bounce lighting; unsuitable for judging final lighting
std/draft4Lighting previewsApproximate indirect lighting with OIDN denoising by default
std/final8Default deliveryApproximate indirect lighting omits some bounce paths
std/path64Interiors, glass and causticsFinite 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.

06Images, video and control channels

Outputs and completion checks

OutputNamingAcceptance condition
PNG still--out preview.pngDefaults to the starting time; preserves alpha
PNG sequence--out frames/Use a directory; PNG numbered filename patterns are unsupported
OpenEXR sequence--out frames/%06d.exrMultilayer, scene-linear and premultiplied alpha; stills also require the numbered pattern
H.264 MP4--out clip.mp4Final alpha must be opaque in every composited frame
ProRes 4444 MOV--out clip.movPreserves 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.

07Iteration, paths and acceptance

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.

08Official scene and expected 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.

json
{"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.

bash
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.mp4

For 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.

09Measurement conditions and comparison limits

Official performance figures

Official caseVork timeComparisonScope
B-interior.json final movie59.231 secondsEEVEE 107.026 seconds240 frames, 1920 × 1080, 24 fps; different sampling and quality
B-night.json final movie92.201 secondsEEVEE 213.477 secondsSame warm movie group; not an equal-quality comparison
Million-bird skim96.942 secondsEEVEE projection at the same 4 samples: 773.7 to 1082.5 seconds192 frames, 1080p; EEVEE extrapolated from a subset of frames
B-car-pan.json path-traced still26.901 secondsCycles 4.632 secondsCarried 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.

10Devices, image quality and failures

Limits and troubleshooting

SymptomCause or limitationAction
nvidia-smi sees a GPU, but Vulkan sees only llvmpipeThe container may be unable to load the NVIDIA ICDCheck driver discovery using the official remote-GPU guide
A new scene takes a long time to produce its first imageNew programs or pipelines need cold compilationRead progress and retain caches; rerun setup after upgrades or driver changes
An interior stays dark after increasing samplesfinal omits some light-transport pathsCompare with path and inspect materials and lights
Glass or dense transparency aborts on MacKnown Metal reliability limitsTry 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 densityArbitrary smoke, grid density and some custom combinations are unsupportedUse homogeneous media or qualified height fog under the fog rules, or composite other effects separately
Output succeeds but an effect looks wrongSome effects are omitted or substituted with a warningInspect 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 codeCategoryNext action
0SuccessInspect fresh metadata, warnings and the image
2Usage errorCheck the command, flags and output naming
3Invalid scene or programFix the schema, resources or Slang program
4Device, GPU memory, encoder or setupAdjust resources or the environment according to the specific error
5Filesystem IOCheck 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.

11Research preview and commercial use

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.

ActivityCurrent license conditions
Internal rendering and delivering finished media to clientsAllowed
Modifications for your own useAllowed
Sharing unmodified copiesKeep the license and all notices
Distributing modified versions, selling or relicensing VorkPrior written permission required
Hosting a rendering service where others submit scenes or jobsPrior 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.

12Advanced shots and adoption

Next steps

  1. Verify a still made with built-in geometry before adding your own glTF model; first fix the camera, resource paths and output specification.

  2. Build downstream handling for depth, normals, object indices and camera data using vork help outputs, and retain completion metadata.

  3. In a source checkout, read the preparation steps and licenses in examples/cake/, examples/vfx-artifact/ and examples/murmuration/ before using their assets.

  4. 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.

bash
blender -b --disable-autoexec source.blend --python integrations/blender/export.py -- --out /tmp/vork-scene

Without 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.

References