Amagine3D: an open-source agent that turns hardware requirements into editable enclosures

What Amagine3D solves, and who it is written for

Most text-to-3D tools end at a mesh. A mesh is a poor starting point for hardware, because the parts you must fit around (boards, connectors, batteries, displays) have measured dimensions, and the shell you print has wall thickness, clearances and a print orientation. Amagine3D targets that gap. The README describes it as an open-source 3D capability layer for hardware creation: you give it a product description and reference images, add the key dimensions, and it designs an enclosure and assembly structures around the internal components while producing source code that stays editable.

The intended user is someone doing mechanical design work in Python, not someone browsing for a 3D model. The project states that manufactured geometry retains editable Python and build123d source and exports genuine STEP, with STL, display GLB and a profile-bound 3MF produced from the same geometry when required. That is a CAD pipeline, and the audience is engineers who can read the generated source and change a parameter.

The current scope is narrower than the tagline suggests. The README says Amagine3D currently focuses on printable intelligent-hardware enclosures and related structures. It is not a general mechanical design system, and it is not a replacement for a parametric CAD package you already know.

The 3D-native Agent loop and the semantic scene it edits

Amagine3D defines what it calls a 3D-native Agent: an agent architecture centered on 3D design state. That 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. The README shows the loop as user requirements and physical constraints feeding an accepted 3D design state, which creates a candidate version that the agent then reads, plans changes against, runs checks on, and either accepts or revises.

Behind that loop, the request becomes an immutable intent plus one mutable semantic scene. Every generation records a single semantic scene containing its parts, features, interfaces, materials, and BRep masters. BRep and color exporters compile that scene into one evidence contract. The agent then sees measured dimensions and checks feature ownership, wall thickness, print orientation, plate fit, connectivity, interference, and exported-file readback, and it renders and reads the latest result before accepting it.

The ordering matters. The design process starts with internal components, arranging mounts and interfaces before creating the enclosure, controls and thermal-management structures. That is the reverse of how many people sketch an enclosure by hand, and it is the reason the agent can check interference at all. The README also gives a concrete example of where a naive check fails: a cavity formed by subtracting an inner loft is checked for actual wall thickness, because section insets alone do not guarantee constant normal thickness.

For appearance-led requests without a supplied visual reference, the workflow asks the agent to use the selected search backend, preferably local a3d search with Tavily, to find relevant sources when network access is enabled. Search snippets remain untrusted leads, and the agent must retrieve and view any image it uses for visual judgment. Engineering dimensions still come from component drawings or explicit assumptions, which is a sensible boundary: search results do not become measurements.

Installing Amagine3D and generating a first enclosure

The repository is private-versioned (package.json says version 0.3.0 and private: true), so there is no package to install from a registry. You clone the repository and run the Node scripts. The engines field requires Node.js >=22.19.0, and the README badge states Node.js 22.19.0+.

The dev script chains the Python setup and then runs the API and web servers together. The Python side is pinned in requirements.txt, with build123d==0.11.1 as the top-level CAD runtime and transitive wheels resolved for the host OS.

npm install
npm run dev

After the script starts, the API listens on the port from the environment and Vite serves the workbench. Copy .env.example to .env and fill in the gateway before the agent can run. The default local ports are 6161 for the API and 6160 for the web UI.

PORT=6161
WEB_PORT=6160
LLM_API_KEY=replace-me
LLM_MODEL=openai/gpt-5.5
LLM_BASE_URL=https://your-gateway.example.com/v1

CODEX_API_KEY and OPENAI_API_KEY are accepted when LLM_API_KEY is unset, and OPENAI_BASE_URL is accepted when LLM_BASE_URL is unset. Two timeouts bound a run: AGENT_RUN_IDLE_TIMEOUT_MS stops the agent after 30 minutes without a Codex event, and AGENT_RUN_HARD_TIMEOUT_MS is an absolute cap of 7200000 ms even when the run stays active.

Before you accept any CAD on visual grounds, check that your model can actually see. Run the vision doctor, which the README says makes two small randomized image requests and leaves diagnostic logs in isolated local sessions. The regular doctor command does not make these API requests.

npm run doctor -- --vision

A successful text response from the model does not establish image perception. If the perception check fails, the README's instruction is to check the model's image support and gateway forwarding before trusting a visual review. For a first real design, supply a product description, reference images and the key dimensions, then let the agent generate; the output you should expect is build123d source, STEP and STL files, and a check report, which the workbench can preview, measure and modify, with parameter changes written back to the source to rebuild the geometry.

Where the pipeline breaks down

The strongest constraint is the model gateway. Visual review uses the generated five-view preview (isometric, front, side, top, bottom) and requires image perception in the configured model or provider. If your gateway strips image attachments or does not forward the native view_image call, the agent cannot judge appearance, and the README is explicit that a rendered PNG or a successful text response does not establish that capability. That is a hard dependency on infrastructure you may not control.

Web research is on by default. CODEX_WEB_SEARCH_ENABLED=true enables both search backends and workspace network access; Tavily is preferred when TAVILY_API_KEY is configured, otherwise Codex hosted search is used when the provider supports it. In an air-gapped environment you set it to false and lose the appearance-led path, which the README frames as the fallback for requests without a supplied visual reference. The managed turns receive only a temporary local search capability, and the account key stays in the runtime.

The geometry kernel is another boundary. The README notes that product envelopes start from a few key sections joined by lofts, with extrusions, revolutions, sweeps and BRep features shaping the rest, and that ruled or segmented surfaces are useful when they preserve the intended form. Loft-and-BRep construction is a poor fit for organic shells, sculpted consumer forms, or anything whose surface continuity is the point. If your design is a smooth handheld casing rather than a box with features, this is the wrong tool.

Finally, the scope statement itself is a limitation. Printable intelligent-hardware enclosures and related structures is what the README claims today. Do not read the BUSY Bar example as evidence of general mechanical capability; it is one multipart enclosure with a display area, top controls and internal space arranged around components and interfaces.

How this differs from scripted build123d and from mesh generators

The obvious alternative is writing build123d yourself. The difference is not the kernel, since Amagine3D uses build123d 0.11.1 and OCP as its runtime. The difference is who decides the sequence. In a hand-written script you choose the order of operations and you are the one checking wall thickness and interference. In Amagine3D the agent owns the loop: it reads the accepted design state, plans changes, runs the checks listed in the README, renders the result, reads it back, and only then accepts the version. If you already have a parametric model and a test suite around it, adding an agent between you and the source is overhead, not help.

The other comparison is with mesh-generation tools that output STL or GLB. Those give you a surface, and you re-model around it if you need to print an enclosure. Amagine3D keeps the BRep masters and the source, so a parameter change rebuilds the geometry rather than re-meshing a fixed shape. The trade-off is that you are constrained to what the kernel and the agent's feature vocabulary can express, which the README's list (lofts, extrusions, revolutions, sweeps, BRep features) makes fairly clear.

A third pattern worth naming is a CAD vendor's built-in scripting API, where the model lives in a proprietary document format and the script is a plugin. Amagine3D inverts that: the source is the artifact, the scene is semantic state, and the exports (STEP, STL, GLB, 3MF) are compiled from it. The 3MF package is profile-bound and can carry permanent color regions inside a physical part, which is a deliberate choice to keep color as model data rather than as a paint step.

Licence, maintenance and what an upgrade costs you

Amagine3D is licensed Apache-2.0, and the repository carries both a LICENSE and a NOTICE file. The package.json declares the same licence. Apache-2.0 is permissive and includes a patent grant, but the NOTICE file means attribution obligations travel with redistribution; if you ship generated designs or the tool itself inside a product, read the NOTICE rather than assuming the licence header is the whole story. There is a licenses:check script and a licenses:update script that maintain an npm licence inventory, which suggests the maintainers track dependency licences deliberately. That is not legal advice, and the Python side pulls in its own wheels (build123d, lib3mf, manifold3d, networkx, numpy, pillow, rtree, trimesh) whose licences are separate.

On maintenance, the repository is not archived and the last push was on 2026-09-16. There are no retrieved releases, so version 0.3.0 in package.json is the only version marker you can rely on, and the project is explicitly private: true, meaning it is not published as a consumable package. Upgrading is therefore a git operation against main, not a version bump in a lockfile you control.

The pinned requirements.txt is the real upgrade surface. The comment says the top-level CAD runtime is pinned and transitive wheels are resolved for the host OS, so a build123d bump is a deliberate edit rather than something a resolver does for you. Budget for re-running the Python tests (npm run test:python) and the TypeScript suite (npm test) after any change to those pins, and expect the check report on an existing project to change when the kernel changes.

Editorial conclusion

Adopt Amagine3D if you already work in Python CAD and want enclosure, mount and assembly geometry generated around internal components, with build123d source you can edit afterwards. Do not adopt it if you need a hosted service, or if your configured model cannot accept image attachments and native view_image calls, because visual review stays incomplete in that case. Before trusting a result, run npm run doctor -- --vision against your gateway, confirm the Python runtime pinned in requirements.txt builds on your host, and open the exported STEP in your own CAD tool.

Frequently asked questions

Official sources

1. amagine-ai/Amagine3D on GitHub
2. Issues
3. License: Apache-2.0
4. README