DEVELOPMENT BUILD · API VOXELITE.V1

Getting started

Install Voxelite. Connect your agent. Make your first model.

Just exploring? Try the web editor on desktop.
Keyboard & mouse required · 1024 × 640 minimum.

Build from source

Install Rust with rustup, then run from a repository checkout. The pinned toolchain is Rust 1.99.1.

export PATH="$HOME/.cargo/bin:$PATH"
cargo build --locked --release \
  -p voxelite-app -p voxelite-mcp
./target/release/voxelite

Download the native Mac app for macOS 13+ on Apple silicon, with installation and first-launch instructions. This build isn't notarized yet. Homebrew packages are not available yet. On macOS, install the Xcode command line tools (xcode-select --install) before building. This native target is wired through GPUI, but has not been built on this Linux machine. Linux native compilation and capture are verified with X11/Xvfb and Mesa software rendering.

sudo apt-get install build-essential pkg-config clang libclang-dev \
  libxkbcommon-dev libxkbcommon-x11-dev libwayland-dev libvulkan-dev \
  libx11-xcb-dev libxcb1-dev libfontconfig-dev libasound2-dev libssl-dev \
  mesa-vulkan-drivers dbus-x11 xdg-desktop-portal xdg-desktop-portal-gtk

cargo build --locked --release -p voxelite-mcp
cargo test -p voxelite-app --no-default-features

Build the web editor and site

scripts/build-site.sh
python3 -m http.server 8090 --directory site --bind 127.0.0.1

Open http://127.0.0.1:8090; the editor lives at /app/. The script builds the shared GPUI app for wasm, generates these docs from Rust, and copies web/dist/ to site/app/. It installs the wasm target and matching wasm-bindgen CLI if needed. For site-only iteration after a web build, use scripts/build-site.sh --skip-web.

Use localhost or HTTPS for browser graphics. WebGPU is preferred and WebGL2 is the fallback. A query of ?backend=webgl forces WebGL2. Save downloads a .voxl; download before reloading to preserve your edits. Browser MCP pairing and project recovery are not implemented.

Make your first edit by hand

1. Open the bundled Autumn Workshop. Right-drag to orbit; wheel to zoom; press F to frame.
2. Select a visible, unlocked layer and a palette swatch. Press B to place on a face, E to erase, or P to paint.
3. Use Ctrl/Cmd + Z to undo. Ctrl/Cmd + K opens command search.
4. Choose File → Save As for your own .voxl. Export GLB or PNG through the File menu or command search.

Connect your agent

Build voxelite-mcp first. Choose one of these modes; each standalone process owns its own in-memory documents.

Headless: create and save independently

Use an existing directory as the file root. Substitute absolute paths for the placeholders below; they are examples, not commands to run unchanged.

{
  "mcpServers": {
    "voxelite": {
      "command": "/absolute/path/to/voxelite-mcp",
      "args": ["--root", "/absolute/path/to/project"]
    }
  }
}

Merge that entry into .mcp.json for Claude Code or .cursor/mcp.json for Cursor. For Codex, merge this table into your trusted project's .codex/config.toml or user ~/.codex/config.toml:

[mcp_servers.voxelite]
command = "/absolute/path/to/voxelite-mcp"
args = ["--root", "/absolute/path/to/project"]

Preserve existing settings. Reconnect the host, list tools, then call voxelite_capabilities_get. Expect API voxelite.v1, an epoch, CPU rendering, and open document IDs. Host launches are not verified in this headless environment. See the official Claude Code, Cursor, and Codex MCP documentation for host-specific setup.

Native: work in the same document

./target/release/voxelite --session-socket /tmp/voxelite-session.sock

Configure the host's executable as above, replacing its arguments with ["--connect", "/tmp/voxelite-session.sock"]. The socket path must not already exist. Or copy the configuration from Agent → Agent connection in the editor. Discover the existing model with capabilities; do not create a second document.

Watch committed calls in Session, pause new writes, and undo or edit by hand. The attached catalog excludes document create/open/save: the native editor owns file lifecycle. Save through the app. Browser sessions cannot attach yet.

Your first model through MCP

In standalone mode, ask your connected agent:

Build a 32 × 32 × 32 clay tower using one atomic box batch. Discover the epoch first. Inspect iso, front, right, and back PNGs, then save first-tower.voxl and export first-tower.glb. Use returned IDs and revisions for each write.

A minimal call sequence follows. These are tool argument objects, not full JSON-RPC messages. Replace placeholders with returned values, and generate a fresh UUID for each new mutation.

1. Discover, then create

Call voxelite_capabilities_get with {}, then voxelite_document_create:

{
  "name": "First tower",
  "bounds": {"min": [0, 0, 0], "max": [32, 32, 32]},
  "expected_epoch": "<returned epoch>",
  "operation_id": "<fresh UUID>"
}

2. Batch the blockout

Call voxelite_voxels_batch. A new project has a Base layer and clay at slot 1.

{
  "model_id": "<returned model_id>",
  "expected_epoch": "<returned epoch>",
  "expected_revision": "<current revision>",
  "operation_id": "<fresh UUID>",
  "label": "Block out tower",
  "operations": [
    {"kind": "box", "layer": "Base", "slot": 1,
     "region": {"min": [10, 0, 10], "max": [22, 2, 22]}},
    {"kind": "box", "layer": "Base", "slot": 1,
     "region": {"min": [13, 2, 13], "max": [19, 18, 19]}},
    {"kind": "box", "layer": "Base", "slot": 1,
     "region": {"min": [11, 18, 11], "max": [21, 20, 21]}}
  ]
}

3. Inspect real pixels

Call voxelite_render and inspect the returned image block:

{
  "model_id": "<returned model_id>",
  "views": ["iso", "front", "right", "back"],
  "width": 512, "height": 512,
  "image_mode": "contact_sheet",
  "revision": "<current revision>"
}

4. Save the result

Call voxelite_document_save with the latest captured revision:

{
  "model_id": "<returned model_id>",
  "expected_epoch": "<returned epoch>",
  "expected_revision": "<current revision>",
  "operation_id": "<fresh UUID>",
  "path": "first-tower.voxl"
}

Then call voxelite_export_glb. Exports use revision, without mutation guards or operation IDs:

{
  "model_id": "<returned model_id>",
  "revision": "<current revision>",
  "path": "first-tower.glb"
}

Save before disconnecting: edits and undo history live in memory. Existing export paths reject; choose a fresh output name.

When a call fails

Check isError and the structured envelope's ok flag. On a revision conflict, read current state and rebase. On a lost response, retry only the identical request with the same operation ID in the same session. Never guess whether an edit committed. Read the error guide before retrying.