Probe

Wright

Public-alpha, local-first agent orchestration for physical engineering.

Public Alpha Status

Wright is alpha software for developer testing, MCP porting, demos, and selected beta feedback. Expect rough edges, incomplete workflows, and changing APIs.

The status badges above are pinned to the production branch, main. Integration work happens on dev, so dev CI may fail while production remains green; use the GitHub Actions branch filter when checking a specific branch.

Wright is bring-your-own-AI. The repository and Docker image do not bundle an LLM, API key, local model, hosted model, or paid engineering backend. Configure LLM_API_URL, LLM_API_KEY, and LLM_API_MODEL for an OpenAI-compatible endpoint, a local model server, or a hosted provider.

MCP-specific host software such as FreeCAD, OpenSCAD, CalculiX, Blender, vendor CAD systems, license managers, or hardware drivers is installed only for the selected MCP validation or usage case. It is not part of the base Docker image. Engineering MCP server validation follows the clean-container process.

Why Wright?

Engineering teams need AI-assisted workflows without handing every design to a single hosted black box. Wright coordinates agents and deterministic tools while leaving LLM/provider choice, credentials, licenses, and host software under the operator's control.

Engineers build a process with blocks, connections and source, then carry out that same process in a working view inside a Wright workspace tab. They can provide inputs, inspect designs and calculations, trace findings to their evidence, and respond at declared questions or review steps. An optional AI-created interface can present the job as a dashboard, comparison or guided sequence.

The workflow platform vision and process UI design keep these experiences on shared execution, validation and storage services. Engineering tools remain independent MCP providers. Manufacturing is one use; analysis, investigation and documentation can use different workflow structures.

The first public alpha is aimed at developers, MCP porters, demo users, and selected beta feedback. Local and hybrid deployments are supported, but real engineering toolchains still require explicit configuration.

What Works Today

• A graphical workflow editor with typed connections, source editing, inspectors, undo/redo and saved definitions.
• Common working views for inputs, progress, results and deliberate user decisions; optional AI-created interfaces that can be previewed, saved and reused.
• Inspectable workflow/step instructions and assumption policy, saved with the workflow. Export/import includes required supported dependencies and diagnoses capabilities that must be configured in the receiving workspace.
• Durable runs, declared input/review checkpoints, output checks and exact evidence links. A successful tool call alone does not establish an engineering pass.
• Ten versioned engineering workflow templates that create editable workspace workflows with recorded origins, readiness disclosures, and durable approval checkpoints.
• MCP tool registry metadata and selected-server validation paths.
• Deterministic CAD, CAE, CAM, and calculation tool actuation through adapters.
• Docker appliance for the Wright API, static web UI, Hermes profile/bootstrap, and general validation tooling.
• A manager-neutral packaged runtime with a production Hermes Git adapter and a direct MCP profile for Codex. Using Codex as Wright's replacement agent runtime is a separate integration project; OpenClaw integration remains future work.
• BYO-AI configuration for local or hosted OpenAI-compatible endpoints.

The Docker appliance is not a complete CAD/CAE/CAM workstation and does not silently install every possible backend.

These descriptions cover the current development source. Published releases may lag it. The workflow editor and process views require their build configuration; see the current-source setup and user guide. Provider availability, licensing and engineering acceptance must be established for the selected workflow.

User Interface

1. Build: use Workflows for a blank process, or open a saved workflow or template. Add inputs and tasks, select workspace MCP providers, and connect the outputs that the next step needs.
2. Prepare: save, choose Open working view, supply inputs and resolve readiness findings before starting.
3. Follow and inspect: view progress, open actual output files and validation evidence, and answer only the interactions declared by the process.
4. Return: use the saved run's working view to inspect the same durable run. Opening it does not repeat completed work.

See the illustrated workspace guide and working-view reference for current controls, screenshots and limitations. Agent chat, workspace files and the tool registry support these journeys in the same workspace.

Current development UI: the saved process is waiting for its declared intent review. Evidence is available; the design has not been approved or manufactured.

Quick Start

Native Hermes (Primary User Path)

Hermes is Wright's primary manager path. Hermes uses Git for plugin installation, so Git is its one adapter prerequisite; Wright itself does not require Docker, Node.js, npm, a Wright checkout, WRIGHT_REPO_DIR, or a manual Python package command. Install the thin production adapter through Hermes:

hermes plugins install https://github.com/burhop/hermes-plugin-wright --enable

Then use /wright start, /wright status, /wright doctor, /wright stop, /wright update, /wright rollback, /wright uninstall, and the separately confirmed /wright purge. See the native Hermes guide for data behavior and the live availability gate.

Docker Appliance

Docker is the mandatory turnkey path for users who want a working appliance without Hermes setup. Published release images use burhop/wright:<tag> on Docker Hub and ghcr.io/burhop/wright:<tag> on GHCR.

With a release image and an env file:

cp docker/.env.example docker/.env
# Edit docker/.env and set LLM_API_URL, LLM_API_KEY, and LLM_API_MODEL
docker run --rm -p 127.0.0.1:8080:8000 --env-file docker/.env burhop/wright:<tag>

From a source checkout while developing or before a release image is cut:

git clone https://github.com/burhop/wright.git
cd wright
cp docker/.env.example docker/.env
# Edit docker/.env and set LLM_API_URL, LLM_API_KEY, and LLM_API_MODEL
docker compose -f docker-compose.minimal.yml up -d --build

Then open:

http://localhost:8080

The default docker-compose.yml also starts Jaeger and maps Wright to http://localhost:8000. See the Docker quickstart and Docker deployment guide for LAN access, local model server, persistent volume, and cleanup examples.

An experimental MCP-enabled appliance flavor is documented in the MCP Docker quickstart. It keeps the same Wright UI access pattern but uses separate default volumes and a reviewed MCP bundle. The managed platform image matrix is documented in the Docker image family guide.

For development outside Docker, see CONTRIBUTING.md.

Images and Releases

Public release images are published as:

burhop/wright:<tag>
ghcr.io/burhop/wright:<tag>

wright-engineering is the one complete public application distribution used by every supported manager adapter. The Hermes repository is a standard-library-only Git adapter; Codex connects directly through an MCP profile. Neither adapter duplicates Wright lifecycle or application code, and the public wheel has no dependency on private wright-* packages.

Every production release requires both the published native Hermes lifecycle and byte-identical Docker publication to GHCR and Docker Hub. Prerelease tags such as v0.1.0-alpha.1 do not move latest; stable tags may.

Architecture

Wright is a modular monorepo with a FastAPI gateway, React/Vite web UI, agent-neutral workspace services, Hermes and future runtime adapters, an MCP tool registry, and local workspace state.

Workspace Artifacts

Models, drawings, images and verification documents are kept in the workspace volume or checkout you control. Open them through Workspace Files or a workflow's results. SQLite stores durable run state and artifact references; files retain their exact revisions and remain available after a view closes.

flowchart TD
    User([User Web Browser]) -->|HTTP / WebSockets| API[FastAPI API Gateway]
    API -->|Thin HTTP translation| Workspace[Workspace Service]
    Workspace -->|Runtime selection and context| Agent[Agent Adapters]
    Workspace -->|Tool assignment and policy| MCP[MCP Tool Registry]
    API -->|Catalog and lifecycle reads| MCP
    Agent -->|Wright gateway protocol| MCP
    MCP -->|Selected server| Tools[CAD, CAE, CAM, calculators]
    API -->|State, files, and logs| LocalState[SQLite and local workspace files]

Hermes remains the default first-class adapter, but .hermes.md and ~/.hermes profile behavior lives in Hermes adapter/profile code. Generic workspace lifecycle code delegates context materialization through packages/agent_adapters contracts so OpenClaw and future engines can plug in without inheriting Hermes file formats.

Repository Structure

wright/
|-- apps/
|   |-- api/                    # FastAPI gateway
|   `-- web/                    # React + Vite frontend
|-- packages/
|   |-- core/                   # Shared domain models and logging
|   |-- agent_adapters/         # Adapter pattern for agent runtimes
|   |-- workspace_service/      # Workspace application use cases and local adapters
|   |-- tool_registry/          # MCP registry and validation logic
|   `-- data_vault/             # SQLite lifecycle, repositories, and secret storage
|-- hermes-plugin-wright/       # Wright Hermes plugin compatibility package
|-- tests/
|   |-- ui-integration/         # Playwright integration tests
|   `-- e2e/                    # Smoke and system tests
|-- docker/                     # Dockerfile and supervisord configuration
|-- docs/                       # Documentation site content and runbooks
|-- specs/                      # Spec Kit feature artifacts
`-- .github/                   # Community templates and CI workflows

Refer to docs/virtual_engineer_architecture.pdf for the formal architecture analysis and constitution.md for core project engineering standards.

Development

Run the main local quality gates:

uv run --extra runtime --extra engineering-models python -m pytest
uv run ruff check apps/api/ packages/
uv run ruff format --check apps/api/ packages/
npm ci
npx -w apps/web eslint .
npx prettier --check apps/web/
npx tsc --noEmit -p apps/web/tsconfig.app.json
npm run test --workspace=apps/web
npm run build --workspace=apps/web
mkdocs build --strict

Run repository-wide and history-sensitive checks from a full clone. If an existing checkout is shallow, fetch the missing history first with git fetch --unshallow (or use git fetch --depth=<larger-number> when a full history download is impractical).

Helper scripts live in scripts/, including public-alpha leak scans, Docker smoke tests, CI failure log fetching, and release checks.

Spec Kit

Wright uses spec-kit for design-led feature work. Most substantive changes should start with a feature spec, plan, tasks, and implementation checklist under specs/.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for local setup, branch discipline, testing, pull request expectations, and the Spec Kit workflow.

Looking for a place to start? Browse issues labeled good-first-issue.

Community and Support

• Ask usage questions in GitHub Discussions.
• Contact maintainers for support, sponsorship, and partner questions at wright@makerengineer.com.
• Report reproducible bugs with GitHub Issues.
• Report security issues privately using SECURITY.md; do not open public security issues.

Support and Sponsorship

Wright is open source, but integration testing, model evaluation, and engineering tool adapters require ongoing resources.

• API, token, and compute sponsorships help cover continuous LLM testing.
• Hardware contributions help test local-first and air-gapped deployments.
• Tool ecosystem contributions help expand the MCP catalog safely.
• Code, docs, and Spec Kit contributions help harden the public alpha.

Sponsor Wright on GitHub

License

This project is licensed under the MIT License. See LICENSE.

Star History and Contributors