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 ·
简体中文
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.
Amagine3D 是一个开源的 3D 能力层：你只需提供产品描述、参考图片和关键尺寸，它的 AI 智能体就会设计一个可 3D 打印的硬件外壳，附带可编辑的 Python CAD 源代码，并导出 STEP、STL 和 3MF 文件。