Amagine3D

From Requirements to Editable Hardware Structures

Amagine3D currently focuses on printable intelligent-hardware enclosures and related structures, creating complete designs from natural-language requirements, reference images, dimensions, and existing geometry.

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 records one semantic scene containing its parts, features, interfaces, materials, and BRep masters. Manufactured geometry retains editable Python and build123d source and exports genuine STEP. Product envelopes start from a few key sections joined by lofts; extrusions, revolutions, sweeps, and BRep features shape the rest of the design. Ruled or segmented surfaces are useful when they preserve the intended form. The same geometry produces STL, display GLB, and a profile-bound 3MF package when required, including permanent color regions inside a physical part.

Behind the scenes, the 3D-native Agent turns the request into an immutable intent and one mutable semantic scene. BRep and color exporters compile that scene into one evidence contract. The Agent sees measured dimensions and checks for feature ownership, wall thickness, print orientation, plate fit, connectivity, interference, and exported-file readback, then renders and reads the latest result before accepting it. A cavity formed by subtracting an inner loft is checked for actual wall thickness; section insets alone do not guarantee constant normal thickness.

For appearance-led requests without a supplied visual reference, the workflow asks the Agent to find and actually view a few relevant images when network access is enabled, record their sources and useful form relationships, and compare an early primary-form preview before developing detail. Engineering dimensions still come from component drawings or explicit assumptions.

Visual review uses the generated five-view preview (isometric, front, side, top, bottom) and requires image perception in the configured model/provider. A rendered PNG or successful text response does not establish that capability. Run npm run doctor -- --vision to check both image attachments and native view_image with two small, randomized image requests. This opt-in check uses the configured model/API account and leaves diagnostic logs in isolated local sessions. A failed perception check means visual review remains incomplete; check the model's image support and gateway forwarding before accepting CAD on visual grounds. The regular doctor command does not make these API requests.

Example: BUSY Bar Desktop Device Enclosure

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.

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.

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. All candidate changes stay inside the isolated session workspace.

The current release uses a semantic scene as that design state. It records physical parts, feature ownership, interfaces, materials, BRep masters, and artifact bindings while keeping the original intent immutable. Each manufactured part remains a valid BRep solid, including lofted enclosures and mechanical structures. The exporters publish the same build-report schema and explicit semantic-to-print coordinate transforms; display and print meshes are derived from the manufactured geometry.

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.

Amagine3D will continue enriching this shared 3D context with component semantics. The system should know whether a model represents a screen, battery, PCB, or connector, how it is mounted, which spaces must remain clear, and which openings and enclosure dimensions it affects, then update related structures when the component changes.

Future inputs may include meshes, scans, and point clouds alongside reference images and component geometry. They can supply scale, landmarks, and spatial context for editable CAD. The current generation workflow focuses on BRep construction and verified manufacturing outputs.

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 22.19.0 or newer
• Python 3.10 through 3.13
• npm
• A modern desktop browser
• An OpenAI Responses-compatible API key or model gateway

The setup script creates a repository-local .venv and installs the pinned build123d, OCP, Manifold, trimesh, and lib3mf dependencies. A desktop CAD application is not required.

Install and Run

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. npm install also installs the platform-specific Codex runtime used by the SDK; users do not need a separate global Codex installation.

Server Configuration

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
CODEX_WEB_SEARCH_ENABLED=true

PORT=6161
WEB_PORT=6160
AGENT_RUN_IDLE_TIMEOUT_MS=1800000
AGENT_RUN_HARD_TIMEOUT_MS=7200000

These values are read only by the local Express server. Existing CODEX_API_KEY/OPENAI_API_KEY and OPENAI_BASE_URL values are accepted when the corresponding LLM_* value is absent. Native Codex live web search and workspace network access default to enabled, with no separate search-service key. Only CODEX_WEB_SEARCH_ENABLED=false in the server environment disables them; there is no browser toggle, and chat-request fields cannot override this setting. Restart the server after changing it. Configuration does not verify that a particular provider supports search, image retrieval, or image perception: health reports search configuration and an untested verification status without making provider calls. Do not expose API keys through client-side environment variables or commit .env.

Each turn runs with workspace-write and approvalPolicy: never: Codex can work freely inside that session's execution directory without UI approval, but writes outside it remain sandboxed. Spawned commands receive a minimal shell environment with secret-like variables removed. The idle timeout is refreshed by native Codex events, and the hard timeout is an absolute per-turn safety cap.

System Architecture

React/Vite UI -> Express API -> Codex SDK/runtime -> isolated workspace -> a3d/Python CAD

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                  Validated image input
│   └── app.ts, index.ts             Express startup, static hosting, and runtime wiring
├── packages/a3d-runtime/
│   └── src/                       Codex adapter, stable events, sandbox, and run supervision
├── bin/a3d                         Session-safe CAD command line
├── skills/
│   └── text-a3d/                  Compact CAD guidance and semantic-scene compilers
│       └── color/BACKEND.md       Internal color-region, material, and 3MF backend
├── 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

The private @amagine3d/a3d-runtime package starts or resumes one native Codex thread per product session and translates SDK events into a stable application contract. The Express server persists product sessions and streams those events to the workbench without importing Codex SDK types. The product layer adds only compact AGENTS.md guidance and the text-a3d skill. The a3d command wraps the existing managed Python compiler, validation, packaging, and rendering entry points; Codex decides when to use them instead of following a server-owned repair state machine.

Every session has its own workspace and Codex state directory. Editable source, manufacturing files, reports, and previews stay together there, while the browser renders generated models with Three.js. For more detail, see the threat model and security reporting policy.

Project Status

Amagine3D is under active development. The current public release focuses on single- and multi-color printable BRep geometry, combining section-controlled lofted envelopes with parametric mechanical structures. Surface continuity can remain coarse while the design keeps valid solids, editable source, genuine STEP, and manufacturing checks. 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 and run the repository checks:

npm run typecheck
npm test
npm run build

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

Core Dependencies and Acknowledgments

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.

License

Amagine3D is licensed under the Apache License 2.0.

Copyright 2026 amagine-ai. See NOTICE for details.