Vysion

Rapid prototype and environment visualization. Photograph a space, describe the change you want, and Vysion renders concept images (OpenAI image models) and explorable 3D worlds (World Labs Marble, viewed in the browser with Spark).

One static Go binary serves the API, the embedded web UI, the job workers, the metering ledger, and the MCP tool gateway that agents and users drive the pipeline through. Agent runs execute as Umbra cells.

• CONCEPT.md: the original brief.
• docs/design.md: the architecture and the decisions behind it.
• CLAUDE.md: working conventions.

Quick start

Requires Go 1.26+, Node 22+, Git LFS, and a sibling checkout of Umbra at ../umbra.

The renderer's assets in worker/render/assets (3D models, their reference photos, art, rugs, textures, skies) are in Git LFS: run git lfs install once before cloning, or git lfs pull after. They are made with the scripts in worker/render/tools from models.json and props.json; a new or remade one is committed like any other file, so every machine renders with the same models. Lock a model before remaking it (git lfs lock <file>, then git lfs unlock once pushed), and have pushes check others' locks: git config lfs.https://git.nytra.io/core/vysion.git/info/lfs.locksverify true.

make web-install web build                      # web/dist, then bin/vysion with it embedded
./bin/vysion admin create-user --email you@example.com --password '…' --admin
OPENAI_API_KEY=… WLT_API_KEY=… ./bin/vysion serve --dev

Open http://127.0.0.1:8080. API docs are at /api/v1/docs, metrics at /metrics. Add provider keys under Admin › Agents (sealed with secret.key in the data directory); the environment variables above are an optional fallback. Until a key exists the pipeline reports that the provider is not configured.

During UI work run make dev in one terminal and cd web && npm run dev in another; Vite proxies the API to the Go server.

The runtime

--runtime local (the default) runs each agent as an unisolated local subprocess through Umbra's fake backend. It is for development and CI only.

--runtime nodes runs agents only on enrolled Umbra nodes, which dial in over WebSocket-over-TLS:

./bin/vysion admin enroll-node --name box1 --runtime docker   # prints UMBRA_NODE_TOKEN
# on the node:
UMBRA_NODE_TOKEN=… umbra-node connect --daemon-url https://vysion.example --runtime docker

The cell image is deploy/agent/Dockerfile: CA certificates plus umbra-guest and vysion-agent. Cells hold a run token only; every provider call goes through the server's MCP gateway, which enforces quotas and writes the ledger.

MCP

The gateway is at /mcp (streamable HTTP). Create an API key in the UI or via POST /api/v1/auth/api-keys, then point any MCP client at it with Authorization: Bearer vys_sk_…. Tools: get_project, list_assets, get_asset, list_renders, get_render, generate_concept, request_world, report_progress.

Layout

cmd/vysion          the binary (serve, migrate, admin, openapi)
cmd/vysion-agent    the guest payload that runs inside a cell
internal/server     huma API, SSE, content, embedded UI
internal/gateway    MCP tool server
internal/agent      Umbra seam: runs, receiver, placers, payload, prompts
internal/pipeline   provider calls: concepts (OpenAI), worlds (World Labs)
internal/usage      ledger, rollups, quotas, reservations
internal/jobs       job table + worker pool
internal/store      sqlc + SQLite, embedded migrations
internal/blob       content store (local; S3 later)
web/                Vite + React + Tailwind, embedded via web/embed.go
deploy/agent        the cell image