Docs

Glyphae is a CLI-native spectral path tracer. Scenes are programs, a live viewport mirrors your state, and the same scene renders draft or final. This page is the human version of glyphae --help-ai, which the binary prints for your agent. First time here? Getting started is the minute-long version, and drive it from your agent is the block to paste into your CLAUDE.md.

Install

One binary, no dependencies. Get it from the download page; it picks your GPU on its own (Metal on macOS, Vulkan on Linux). Everything is a compute shader, so a GPU is required — there is no CPU fallback.

# macOS (Apple silicon)
unzip glyphae-*-macos-arm64.zip && sudo mv glyphae /usr/local/bin/

# Linux (x86_64, needs a Vulkan driver)
tar xzf glyphae-*-linux-x86_64.tar.gz && sudo mv glyphae /usr/local/bin/

glyphae --version

The loop

You do not open and close a renderer per change. You keep one viewport up and edit a text file next to it:

glyphae --scene-new tire work.scene     # 1. dump a starting scene
glyphae --view work.scene &            # 2. open the live viewport
                                       # 3. edit work.scene — it hot-reloads
echo '{"cmd":"snapshot","path":"look.png"}' | nc 127.0.0.1 7878
                                       # 4. verify with your eyes
glyphae --render-scene work.scene out.png 2048 1600 2000
                                       # 5. the final, headless

Scene files

A .scene file is text: one key=value per line, # for comments. recipe=<name> picks the geometry program; every other key is a knob. Dump any recipe with --scene-new to discover its full knob list.

# a scene is a plain-text program: one key=value per line,
# # for comments. same input, same pixels, every time.
recipe=tire
camera.yaw=1.5708
camera.pitch=0.06
scene.decal_ink=1.0
params.tire_lugs=15

Knobs come in two tiers, and the difference is speed:

params.* — geometry. Changing one regrows the mesh, so it costs more per edit.
camera.*, scene.* — trace. Changing one only restarts accumulation: fast.

Recipes: blank petrol emerald gem slab card carabiner zen can jelly tire avatar.

The live viewport

glyphae --view [file.scene] opens one window that stays up across your whole session. It watches the file and reloads on save, and it answers newline-JSON on 127.0.0.1:7878 (GLYPHAE_VIEW_PORT overrides):

{"cmd":"ping"}                          -> {"ok":true,"scene":..,"spp":..}
{"cmd":"open","path":"f.scene"}         switch scene
{"cmd":"quality","mode":"fast"|"good"}  64 spp cap vs 4096 spp
{"cmd":"snapshot","path":"out.png"}     write exactly what the window shows
{"cmd":"reset"}                         reload the file (= your state)
{"cmd":"play"} / {"cmd":"pause"}        play/pause an animated scene
{"cmd":"time","t":0.42}                 scrub to a frame, hold it
{"cmd":"clay"}                          clay shading (read the form)

A snapshot writes exactly what the window shows, so you and your agent share one ground truth. Mouse orbits; SPACE play/pause, R reset to file state, C clay, G quality, P save, Esc quit. Window size is GLYPHAE_VIEW_W / GLYPHAE_VIEW_H.

Headless renders

glyphae --render-scene f.scene out.png [spp] [w h]   replay a scene file (finals)
glyphae --render out.png [spp] [w h]                default harness scene
glyphae --cloud out.png [march|path] [spp] [w h]    volumetrics, two transports

Volumes have two transports and you should always be offered both: march is a fast approximation for the feedback loop, path is delta-tracked ground truth. Long jobs write renders/progress.json (job, pct, eta_s) — poll that instead of asking the renderer.

Draft and final

--draft (or GLYPHAE_DRAFT=1) is the validation tier: samples capped at 64, resolution halved, volumes forced to march. It validates motion, framing and timing in seconds, and every clamp logs a warning so a draft never ships by accident.

GLYPHAE_DENOISE=1 — with the denoiser, 128–256 spp reads like 2000. Without it, budget 2048+ spp for glass and caustics, 512+ for diffuse.
GLYPHAE_RT=1 — hardware ray tracing on NVIDIA/Vulkan, 3–11× wall clock (glass gains most). Look-identical, not bit-identical; falls back loudly without ray query.
GLYPHAE_BATCH — samples per dispatch. Output is bit-identical at any batch size.

Driving it from an agent

There is no plugin and no SDK: Glyphae is a binary, so whatever agent you already run in a terminal drives it — Claude Code, Codex, Kimi CLI, or your own harness. The engine documents itself for them: glyphae --help-ai prints a complete manual — scene format, socket protocol, render arms, quality policy — so an agent that finds the binary can learn to drive it without reading a website. Point your agent at that output, keep a viewport open, and make it snapshot before it claims a visual result.

Asset API

Accounts and the asset API still run: sign in at /sign-in, create an API key in /account, and reads are public while writes take a session cookie or an x-api-key header. The machine-readable spec is at /api/openapi.json, and the published index at /data/manifest.json.

curl "https://glyphae.com/api/assets?category=material&q=concrete"

The browse page is gone for now: everything in it was our own work, and a library of our own assets was standing in front of the engine. The API, uploads and every /a/<id> link still resolve, and a community surface comes back when there is community work to put in it.