Amagine3D

From hardware requirements to editable 3D designs

Amagine3D is the open-source 3D capability layer Amagine is developing for hardware creation.
Give it a product description and reference images, add the key dimensions, and Amagine3D can design an enclosure and assembly structures around the internal components while producing source code that remains editable. STEP, STL, and 3MF files can be exported as needed.

Capabilities · Example · Quick Start · 简体中文

A rotating BUSY Bar enclosure generated by Amagine3D

## From Requirements to Editable Hardware Structures Parametric CAD is the first 3D capability delivered in Amagine3D. It currently focuses on intelligent hardware enclosures and related structures, creating complete parametric designs from natural-language requirements, reference images, and dimensions. The design process starts with internal components, arranging mounts and interfaces before creating the enclosure, controls, and thermal-management structures. When a design needs multiple parts, covers, hinges, or latches are developed together with assembly clearances and printing tolerances. For rigid mechanisms such as hinged or sliding covers, the system can also check collisions and operating clearances along a defined motion path. Every generation preserves the complete Python and build123d source code. Key dimensions appear in the workbench, where they can be adjusted and written back to the source without calling the model again. Single-color designs can be exported as STEP and STL, while multi-color designs can produce color-aware 3MF files and separate STL files for each color region. Behind the scenes, the 3D-native Agent first organizes the requirements into a design brief, then runs the source in the browser geometry runtime to build the actual model. The Agent can see the model's real dimensions and receives check results for part connectivity, interference, and motion. Exported model files are read back as well. It uses these results to decide whether to keep revising or accept the current version. ## Example: BUSY Bar Desktop Device Enclosure The GIF above shows a desktop device enclosure that Amagine3D generated from public information about [BUSY Bar](https://busy.app/). BUSY Bar is a productivity multi-tool for displaying custom statuses. It includes a built-in Pomodoro timer and apps, supports extensive customization, is open-source, and is friendly to developers and hardware enthusiasts. Amagine3D created a multipart enclosure for it, with a display area on the front, physical controls on top, and internal space arranged around the components and interfaces. The Agent first used the reference images to position the display area and controls, then divided the enclosure into parts around the internal components. The dimensions that determine appearance and assembly remain editable parameters, so they can be adjusted after generation. This generation produced complete build123d source code, STEP and STL files, and a check report. The workbench can continue to preview, measure, and modify the model. Parameter changes are written back to the source and rebuild the geometry, and the complete result is saved with the project. Design reference: [BUSY Bar official website](https://busy.app/). ## 3D-native Agent Amagine3D defines a 3D-native Agent as an Agent architecture centered on 3D design state. This state records the geometry of every part in the current version and the spatial relationships between them. It determines the Agent's next action, and execution results are written back into it. ```text User requirements and physical constraints │ ▼ Accepted 3D design state │ create candidate version ▼ ┌── autonomous inner loop ──┐ │ read model → plan changes │ │ ↑ ↓ │ │ analyze results ← run checks│ └─────────────┬──────────────┘ │ checks pass ▼ Commit as a new version │ ▼ Save state and artifacts ``` In this architecture, a design task has two levels. The autonomous inner loop produces candidate designs, while the commit stage decides whether a candidate can become the new accepted version. Keeping them separate lets the Agent try repeatedly without damaging a design that has already passed its checks. Each iteration of the autonomous inner loop starts from the current design state. The Agent reads the spatial relationships between parts, then decides which structures need to change. The modified model runs in a real geometry environment, where the system measures the generated result directly and checks assembly interference, motion paths, and exported files. These results return to the Agent. If a requirement is not satisfied, the Agent uses the specific measurements to locate the problem, modifies the affected area, and starts another iteration. This process works from the geometry that was actually generated, rather than the model's textual judgment of the result. Once a candidate design meets the checks for the current task, it enters the commit stage. The system compares the candidate with the user constraints and the previous design version. If the checks pass, the candidate is saved as the new baseline, together with its source code and manufacturing files. If the change introduces a new problem, the system preserves the previous result and lets the Agent continue correcting the candidate. Changes to confirmed structures or overwrites of existing artifacts can require user approval. The current public release implements the first stage of this process with parametric CAD. The Agent generates build123d source code from a design brief, builds the geometry in the browser, and then revises or accepts the candidate according to the check results. For now, source code remains the primary design state, and tasks advance through predefined stages. The next stage will record parts and their spatial relationships directly in a continuously updated 3D world-model state. The Agent will then be able to modify local structures or switch geometry representations within that state without reconstructing the entire design from conversation and source code each time. ## Beyond CAD CAD is the starting point for Amagine3D. Complete hardware creation also requires an understanding of physical components, spatial relationships, and existing assets, so 3D information from different sources can continue flowing between design and manufacturing. In the next stage, Amagine3D will progressively build a shared 3D context for each hardware project. The system will know whether a model represents a screen, battery, PCB, or connector. It will understand how the component is mounted, which spaces must remain clear, and which openings and enclosure dimensions it affects, then update related structures when the component changes. The paths into 3D will also expand from natural-language generation to meshes, images, scans, and point clouds. Precise structures can continue to use parametric CAD, exterior forms can come from generative meshes, and physical objects can enter the project through 3D reconstruction. The Agent will choose the representation that fits the task while sharing parts, scale, position, and design intent across them. This 3D state will extend into manufacturing as well. Geometry repair, wall thickness, scale, print orientation, supports, and manufacturing files will become part of how the Agent advances a hardware project, rather than separate steps that begin after design is complete. Our goal is to let a hardware concept begin with reference images, physical components, and spatial constraints, then grow through one continuous 3D design process into a product that can be assembled and manufactured. ## Quick Start ### Requirements - Node.js 20.19 or newer - Python 3.10 through 3.13 - npm - A modern desktop browser - A model gateway compatible with an Amagine3D Agent runtime protocol The setup script creates a repository-local `.venv` and installs the pinned build123d, OCP, trimesh, and lib3mf dependencies. A desktop CAD application is not required. ### Install and Run ```bash git clone https://github.com/amagine-ai/Amagine3D.git cd Amagine3D npm install cp .env.example .env npm run dev ``` Configure `.env`, then open `http://127.0.0.1:6160`. The local API listens on `http://127.0.0.1:6161` by default. The first start prepares `.venv`; later starts reuse it when the dependency fingerprint is unchanged. ### Server Configuration ```dotenv LLM_API_KEY=... LLM_MODEL=openai/gpt-5.5 LLM_BASE_URL=https://gateway.example.com/v1 LLM_API_TYPE=openai-responses LLM_THINKING_LEVEL=medium TAVILY_API_KEY=... # optional; enables the Web refs control PORT=6161 WEB_PORT=6160 AGENT_RUN_TIMEOUT_MS=1800000 ``` These values are read only by the local Express server. When `TAVILY_API_KEY` is configured, the composer exposes a **Web refs** control. Enabling it for a turn requires Amagine3D Agent to search before CAD mutations, returns ranked dimension/specification sources, and passes up to three available reference images to the multimodal model. Missing images do not block the CAD Skill workflow. Do not expose API keys through client-side environment variables or commit `.env`. ## System Architecture `React/Vite UI -> Express API -> 3D-native Agent runtime -> session-scoped Python CAD workspace` ```text Amagine3D/ ├── src/ │ ├── components/cad-workbench/ Chat, files, preview, parameters, and storage panels │ ├── components/CadViewer.tsx Three.js model viewer and interaction │ ├── lib/ Streaming API client and artifact/session helpers │ └── App.tsx, types.ts App shell and shared contracts ├── server/ │ ├── routes/ Agent chat streaming and session/artifact APIs │ ├── artifacts*.ts, sessions.ts Artifact discovery, archive, trash, and persistence │ ├── uploads.ts, visual-audit.ts Image input and generated-model visual checks │ └── app.ts, index.ts Express startup, static hosting, and runtime wiring ├── packages/a3d-runtime/src/ 3D-native Agent model/session adapter, skill loading, and write guards ├── skills/ │ ├── text-a3d/ Single-color CAD generation and QA workflow │ └── text-a3d-color/ Multi-color CAD, palette, 3MF export, and QA workflow ├── bundled-projects/ Read-only example projects shown in the workbench ├── workspace/sessions// Generated source, models, reports, and previews ├── .amagine-state/ Agent sessions, uploads, and local runtime state ├── scripts/ Python setup and license checks └── tests/ Server, runtime, artifact, and UI-logic tests ``` Each Agent session uses its own workspace. CAD scripts run with the server-managed Python environment, while the browser renders generated models with Three.js. Model credentials remain on the server. For more detail, see the [threat model](./docs/threat-model.md) and [security reporting policy](./docs/SECURITY.md). ## Project Status Amagine3D is under active development. The current public release focuses on single-color and multi-color parametric CAD for intelligent hardware enclosures. The complete workflow has been tested in desktop Chrome and Edge. ## Contributing Focused issues and pull requests are welcome. Before submitting changes, read [CONTRIBUTING.md](./docs/CONTRIBUTING.md) and run the repository checks: ```bash npm run typecheck npm test npm run build ``` Report security issues through the private process in [SECURITY.md](./docs/SECURITY.md). ## Core Dependencies and Acknowledgments Amagine3D is built on the following open-source projects: | Project | Purpose | | ---------------------------------------------------------------------------------------------------------- | -------------------------------------- | | [build123d](https://github.com/gumyr/build123d) | Parametric CAD modeling | | [Open CASCADE Technology](https://dev.opencascade.org/) and [CadQuery OCP](https://github.com/CadQuery/OCP) | Exact geometry kernel and Python bindings | | [Three.js](https://github.com/mrdoob/three.js) | 3D preview, selection, and measurement | | [trimesh](https://github.com/mikedh/trimesh) | Mesh processing and checks | | [lib3mf](https://github.com/3MFConsortium/lib3mf) | 3MF writing and readback | | [PI coding agent](https://github.com/earendil-works/pi) | Agent sessions, streaming, and tool calls | The running application exposes its license page at `/licenses`. Checked-in license texts and the production npm inventory are available under [`public/licenses/`](./public/licenses/). The source-only distribution boundary and third-party attributions are documented in [`THIRD_PARTY_NOTICES.md`](./docs/THIRD_PARTY_NOTICES.md). ## License Amagine3D is licensed under the [Apache License 2.0](./LICENSE). Copyright 2026 [amagine-ai](https://github.com/amagine-ai). See [NOTICE](./NOTICE) for details.