Get started

Your first model

This page follows one small part from a prompt to a file. It assumes you have run the install command and restarted your agent app.

Ask for a part

Open your agent in a folder you want the model to live in, and ask for something plain:

Make a 40 by 20 mm mounting bracket, 6 mm thick, with an 8 mm hole through the middle.

You do not name a skill. The agent picks the cad skill from the request.

What the agent writes

The agent writes a Python script. A model is a function with no parameters, marked @model, that returns a build123d shape. Units are millimetres, with +Z up. A script such as src/bracket.py looks like this:

import build123d as bd
from cad import model


def bracket_body(width, thickness, bore):
    body = bd.Box(width, 20, thickness)
    hole = bd.Cylinder(bore / 2, thickness)
    body = body - hole
    body.label = "bracket"
    body.color = "#4a6fa5"
    return body


@model
def bracket():
    return bracket_body(40, 6, 8)


if __name__ == "__main__":
    bracket()

The dimensions are arguments of a plain helper, so a change is one number. The call under __main__ is what builds the model. Importing the script builds nothing, which lets other scripts, such as an assembly, import the part. Models covers the contract, and project layout covers where scripts go.

What running it prints

The agent builds the script with the cad command:

cad run src/bracket.py

cad run works like uv run, so the script's own packages come from its header. It needs the server running, which your agent starts with cad server start. It prints how the model built, then two lines that matter to you:

  id: 0dc50a92-a21f-5895-a245-ebdeb5352f3b
  view: http://127.0.0.1:54360/0dc50a92-a21f-5895-a245-ebdeb5352f3b?token=...

The id: names the model's document. It comes from the script's path and the function's name, so it is the same on every run. The view: line is its page in the viewer. Your port and token will differ.

See it on screen

Your agent shows you the model. In the Codex app, the viewer opens in a CAD tab beside the thread. In every other app the agent opens the page in the app's browser, or gives you the view: link to open in yours. You can also run cad viewer yourself, which opens the viewer's home. See the viewer.

Ask for a change

Stay in the same conversation:

Make the hole 10 mm and the bracket 60 mm long.

The agent edits the numbers and runs cad run src/bracket.py again. The page you have open updates on its own. The server keeps a warm worker for the script and replays every step the edit did not reach, so a small edit rebuilds quickly.

Export a file

A run writes no files. A model is a document the server holds, and files are made when you ask:

Export the bracket as a STEP file and an STL.

The agent runs cad model export with the model's id:

cad model export "$ID" STEP/bracket.step STL/bracket.stl

$ID is the id: line from the run. The format comes from the file's suffix, and GLB and 3MF work the same way. You can also use Export in the viewer's file menu, which hands you a browser download. An STL for printing a part with fits takes a tolerance, which exports explains.

Where to go next