# Meshwright

**The open 3D generation stack for agents.**

[![Tests](https://github.com/seena18/meshwright/actions/workflows/test.yml/badge.svg)](https://github.com/seena18/meshwright/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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.

```text
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

```bash
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:

```bash
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`](config.example.json): TRELLIS.2 on the same Linux/CUDA
  machine as the pipeline.
- [`config.pc-4080.example.json`](config.pc-4080.example.json): TRELLIS.2 on the
  Windows/WSL 4080 machine over SSH.
- [`config.http.example.json`](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.

```bash
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:

```bash
curl http://localhost:8787/health
```

To update the service:

```bash
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:

```bash
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:

```powershell
.\scripts\windows-open-firewall.ps1
```

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

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

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

```json
{
  "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:

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

```bash
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:

```bash
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:

```bash
pip install -e '.[mcp]'
```

Configure a stdio MCP client with:

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

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