Meshwright

The open 3D generation stack for agents.

Meshwright is an open-source LangGraph pipeline that lets agents create, inspect, retry, and deliver 3D models from generated reference images. Bring your own image provider, vision model, reconstruction backend, and GPU—local or remote.

prompt
  ↓
generate reference image
  ↓
remove background
  ↓
review reference ── reject + feedback ──┐
  ↓ accept                              │
1024 preview                            │
  ↓                                     │
review model ───── reject ──────────────┘
  ↓ accept
1536 final ── failure → 1024 fallback
  ↓
final review
  ↓
GLB

The recommended deployment has two small parts: a viewer/client running the LangGraph workflow and a persistent GPU host that keeps TRELLIS warm. The viewer has native OpenAI image and vision adapters, automatic Blender turntable reviews, optional rembg, and command adapters for local agents such as Codex or Claude Code. Local and SSH TRELLIS backends remain available.

Install

cd meshwright
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Install Blender separately when using native vision review. Its executable must be on PATH, or set renderer.blender to its full path.

Configure

Create a viewer configuration without putting secrets in it:

export OPENAI_API_KEY="..."
export MESHWRIGHT_HOST_TOKEN="..."
meshwright configure \
  --provider openai \
  --trellis-url http://192.168.8.248:8787 \
  --output meshwright.json

meshwright doctor --config meshwright.json

doctor validates provider credentials, Blender, optional rembg, and GPU host connectivity before generation. The OpenAI adapter generates transparent PNG references with gpt-image-2. For each GLB, Blender renders four evenly spaced views and the review model evaluates all of them using strict review JSON. Provider model names and endpoints remain configurable.

A locally authenticated agent CLI can be used through command templates. Point image.command and review.command at small wrappers that call codex exec, claude -p, ComfyUI, or another installed tool and write the requested {output} or {review} file. This preserves on-machine login while keeping the core independent of each CLI's changing flags.

Choose a starting configuration:

• config.example.json: TRELLIS.2 on the same Linux/CUDA machine as the pipeline.
• config.pc-4080.example.json: TRELLIS.2 on the Windows/WSL 4080 machine over SSH.
• config.http.example.json: the recommended persistent GPU host, on a LAN or private VPN.

Plug-and-play GPU host

Platform entry points:

Host	Command	Backend
Linux + NVIDIA	./scripts/install-linux.sh	Official TRELLIS.2 CUDA container
Windows + NVIDIA	.\\scripts\\install-windows.ps1	Same container through Docker Desktop/WSL2
Apple Silicon macOS	./scripts/install-macos.sh	Native community Metal/MPS port

The installers create a random token, start a background service, and expose the same HTTP API on port 8787. Linux still requires Docker Engine, Compose, the NVIDIA driver and NVIDIA Container Toolkit. Windows requires Docker Desktop's WSL2 engine and an elevated terminal for the firewall rule. macOS requires 24 GB unified memory or more for practical use and may require the user to accept/login for gated Hugging Face dependencies.

The macOS backend currently starts the community runner for each request, so it does not yet retain the model between jobs. Its final profile maps to 1024_cascade with 2048 textures; the CUDA final profile remains 1536 cascade.

Container installation (recommended)

The container includes CUDA 12.4 user-space libraries, Python, the official TRELLIS.2 checkout and compiled extensions, and the meshwright API. The machine only needs Docker with NVIDIA GPU support and a compatible NVIDIA driver.

cd meshwright
cp .env.example .env
python -c "import secrets; print(secrets.token_urlsafe(32))"
# Paste the result into MESHWRIGHT_TOKEN in .env.

docker compose build gpu-host
docker compose up -d gpu-host
docker compose logs -f gpu-host

The first image build compiles TRELLIS CUDA extensions and can take a while. The first generation downloads model weights. Both model downloads and job artifacts use named volumes, so subsequent container rebuilds preserve them. Confirm readiness with:

curl http://localhost:8787/health

To update the service:

docker compose build --pull gpu-host
docker compose up -d gpu-host

For reproducible deployments, replace TRELLIS_REF=main in .env with a tested TRELLIS.2 commit hash. The image deliberately does not contain a token or downloaded model weights.

Existing-environment installation

Install TRELLIS.2 and its model once on the NVIDIA machine. Then clone this repo there and run the setup script from Linux or WSL:

cd meshwright
TRELLIS_ROOT=/home/trellis/TRELLIS.2 \
TRELLIS_PYTHON=/home/trellis/miniconda3/envs/trellis2/bin/python \
TRELLIS_MODEL=/home/trellis/models/TRELLIS.2-4B \
./scripts/setup-gpu-host.sh

./scripts/start-gpu-host.sh host.json

The setup validates the GPU, environment, checkout, and model; installs the host into the existing TRELLIS environment; creates a random access token; and runs a readiness check. The first generation loads the model, then it stays in VRAM for later jobs. One worker serializes requests so multiple clients cannot overcommit a single GPU.

On Windows/WSL, allow LAN clients once from elevated PowerShell:

.\scripts\windows-open-firewall.ps1

Create the small pairing file to copy to the viewer machine:

meshwright-host pair \
  --config host.json \
  --url http://192.168.8.248:8787 \
  --output gpu-host.json

Copy the resulting trellis object into the viewer's config.json, or copy its four fields into the trellis section of config.http.example.json. The client uploads an image, polls the queued job, and downloads the GLB; it no longer needs SSH paths, WSL commands, CUDA, or TRELLIS installed locally.

The host currently uses token-authenticated HTTP. Keep it on a trusted LAN or a private VPN such as Tailscale; do not expose port 8787 directly to the public internet. Treat the pairing file like a password.

For local-agent or custom-provider use, set an adapter's type to command and provide an argument array. The pipeline never invokes a local shell.

Available placeholders:

Command	Placeholders
Image	{prompt}, {prompt_file}, {output}, {attempt}, {feedback}
Background	{input}, {output}
Review	{input}, {review}, {kind}, {subject}, {profile}, {output_dir}

The image command must produce a PNG. The background command must produce the clean reconstruction input. The selected TRELLIS backend must produce a GLB.

Local GPU mode

{
  "trellis": {
    "type": "local",
    "python": "/home/trellis/miniconda3/envs/trellis2/bin/python",
    "model_path": "/home/trellis/models/TRELLIS.2-4B",
    "working_directory": "/home/trellis/TRELLIS.2",
    "low_vram": true,
    "environment": {
      "PYTHONPATH": "/home/trellis/TRELLIS.2",
      "ATTN_BACKEND": "flash_attn"
    }
  }
}

The pipeline launches the bundled trellis2_generate.py with the configured Python environment.

Remote GPU mode

{
  "trellis": {
    "type": "ssh",
    "host": "seena@192.168.8.248",
    "identity_file": "~/.ssh/ultimate_operator_pc_ed25519",
    "scp_input_dir": "C:/Users/seena/TRELLIS2/input",
    "scp_output_dir": "C:/Users/seena/TRELLIS2/output",
    "worker_input_dir": "/mnt/c/Users/seena/TRELLIS2/input",
    "worker_output_dir": "/mnt/c/Users/seena/TRELLIS2/output"
  }
}

In SSH mode the pipeline:

1. Uploads the generated reference and bundled runner with scp.
2. Executes the configured launch template on the GPU machine.
3. Waits for TRELLIS.2 to finish.
4. Downloads the resulting GLB.

The included 4080 configuration already contains the Windows OpenSSH and WSL paths used in our previous dragon run. Copy it to config.json and adjust only the image-generation, background-removal, and review commands as needed.

The review command must write this JSON schema:

{
  "accepted": true,
  "score": 88,
  "findings": [],
  "topology_ok": true,
  "all_views_ok": true
}

The native review adapter performs the multi-angle rendering automatically. With a command review adapter, the command owns rendering and must write this schema. Findings from a rejection are added to the next image prompt automatically.

Run

meshwright generate \
  "a charcoal dragon with broad, fully spread red wings" \
  --config config.json \
  --output runs/dragon \
  --attempts 3 \
  --thread dragon-001

The output directory contains generated references, prompts, GLBs, reviews, and checkpoints.sqlite3. Reuse the same thread ID to inspect or resume that graph state.

Browser viewer

Install and launch the local viewer:

pip install -e '.[viewer]'
meshwright-viewer --config meshwright.json --data-dir runs

It opens http://127.0.0.1:8790, where you can submit prompts, watch queued and running jobs, inspect review results, orbit accepted GLBs, and download the artifact. A SQLite queue persists runs and returns interrupted work to the queue after a restart. The viewer binds only to localhost by default; use --bind deliberately if another LAN machine must reach it.

Agent/MCP integration

Install the official MCP Python SDK integration:

pip install -e '.[mcp]'

Configure a stdio MCP client with:

{
  "mcpServers": {
    "meshwright": {
      "command": "meshwright-mcp",
      "args": [
        "--config", "/absolute/path/to/meshwright.json",
        "--output-root", "/absolute/path/to/runs/mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "your-key",
        "MESHWRIGHT_HOST_TOKEN": "your-host-token"
      }
    }
  }
}

The server exposes asynchronous tools so a long GPU run does not hold an MCP request open:

• doctor: checks credentials, Blender, custom executables, and GPU-host health.
• create_3d_job: queues a generation and immediately returns its job ID.
• get_3d_job and list_3d_jobs: report durable status and review results.
• cancel_3d_job: cancels work that has not started.
• get_3d_artifact: returns the accepted GLB's absolute path.

For shared machines, inject secrets through the MCP host's secure environment configuration rather than committing them to the JSON file.

Default quality policy

The pipeline uses two stages:

Stage	Resolution	Texture	Face target
Preview	1024	1024	300,000
Final	1536	2048	600,000

Final generation happens only after the preview passes. If final reconstruction throws an error, the graph retries with the preview profile and still requires the result to pass review.

Before vision review, Blender records mesh count, vertex and triangle counts, dimensions, material count, and non-manifold edges. Empty, nearly empty, or zero-thickness geometry is rejected deterministically without spending another vision request; the remaining metrics are included in the visual review.

Test

pytest

The tests run with fake image, reconstruction, and review adapters. They verify reference regeneration, preview-to-final promotion, checkpoint-compatible state, and final-to-preview fallback without downloading any models.