Amagine3D

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.

The GIF above shows a desktop device enclosure that Amagine3D generated from public information about BUSY Bar. 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.

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.

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.

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.

• Node.js 20.19 or newer
• Python 3.10 through 3.13
• npm
• A modern desktop browser
• A model gateway compatible with one of the PI SDK protocols

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.

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.

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

PORT=6161
WEB_PORT=6160
AGENT_RUN_TIMEOUT_MS=1800000

These values are read only by the local Express server. Do not expose API keys through client-side environment variables or commit .env.

React/Vite UI -> Express API -> 3D-native Agent runtime -> session-scoped Python CAD workspace

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/<sessionId>/   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 and security reporting policy.

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.

Focused issues and pull requests are welcome. Before submitting changes, read CONTRIBUTING.md and run the repository checks:

npm run typecheck
npm test
npm run build

Report security issues through the private process in SECURITY.md.

Amagine3D is built on the following open-source projects:

The running application exposes its license page at /licenses. Checked-in license texts and the production npm inventory are available under public/licenses/. The source-only distribution boundary and third-party attributions are documented in THIRD_PARTY_NOTICES.md.

Amagine3D is licensed under the Apache License 2.0.

Copyright 2026 amagine-ai. See NOTICE for details.