# How to Preview STEP Files Locally with CAD Viewer: A Complete Setup Guide > Easily preview STEP files locally with CAD Viewer. This guide shows you how to set up the lightweight browser viewer to render your local STEP files directly. - Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) - Tags: how-to-guide - Published: 2026-07-22 --- **CAD Viewer is a lightweight browser-based workbench that renders STEP (`.step`/`.stp`) files directly from your local filesystem using URL query parameters to specify the directory and target file.** The earthtojake/text-to-cad repository includes CAD Viewer, a React-based visualization tool for inspecting 3D geometry without external CAD software. This guide explains how to configure the local server, launch the viewer using the built-in agent or Vite dev server, and load your models via the directory-based routing system documented in [`viewer/docs/backend.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/docs/backend.md). ## Installation and Prerequisites Before rendering STEP files, you must install the viewer's JavaScript dependencies from the `viewer/` directory. The project uses **Vite** as the build tool and requires Node.js. Navigate to the viewer directory and install dependencies: ```bash cd viewer npm install ``` This installs the required packages including `vite`, `react`, and the CAD runtime components necessary for parsing STEP geometry. ## Starting the CAD Viewer Server The repository provides two methods to launch the viewer: a standard development server or the intelligent **agent launcher**. Both approaches serve the React frontend defined in [`viewer/src/client/components/StepViewer.tsx`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/src/client/components/StepViewer.tsx), but the agent offers enhanced workflow automation. ### Option A: Standard Vite Development Server Run the following command to start a plain Vite dev server on a specific host: ```bash npm run dev -- --host 127.0.0.1 ``` This binds the server to localhost and prints a local URL (typically `http://localhost:5173`). You must manually append the `?dir=` and `?file=` query parameters to load models. ### Option B: Agent Launcher (Recommended) The agent launcher automatically selects an available port, stores your models directory as a default, and reuses an existing viewer instance if one is already running: ```bash npm run agent:start -- --dir /absolute/path/to/models ``` According to [`viewer/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/README.md), the agent outputs a ready-to-use URL like `http://127.0.0.1:4178`. This mode is particularly useful when integrating with the `$cad-viewer` skill system, as it maintains persistent server state across multiple file openings. ## Loading STEP Files via URL Parameters CAD Viewer reads the filesystem location from two query parameters parsed by the backend logic in `viewer/src/server/localAssetBackend.test.mjs`: - **`?dir=`**: Absolute path to the root directory containing your models - **`?file=`**: Relative path from that root to the specific STEP file Construct the URL by combining these parameters. The file path must be relative to the directory root specified in `?dir=`. Open a specific STEP file using the agent port: ```bash # Assuming agent is running on port 4178 open "http://127.0.0.1:4178/?dir=/home/user/text-to-cad/models&file=assemblies/robot-arm/robot-arm.step" ``` Replace `open` with `xdg-open` on Linux or use the full URL in your browser. The viewer will render the STEP geometry using hidden GLB topology side-cars for fast face and edge picking, as implemented in the rendering pipeline. ## Automating Workflows with the CAD Viewer Skill For integration with the text-to-cad skill system, the `$cad-viewer` skill automates the launch-and-link process described in [`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md). When invoked from another skill, it ensures the viewer is running and returns a markdown link: ```text $cad-viewer /home/user/text-to-cad/models/assemblies/robot-arm/robot-arm.step ``` The skill performs three actions automatically: it launches the viewer if no instance exists, reuses the current port if available, and generates a clickable link following the `?dir=` and `?file=` URL pattern. This eliminates manual URL construction when previewing files generated by other pipeline steps. ## Key Source Files and Architecture Understanding these implementation files helps troubleshoot issues or extend functionality: - **[`viewer/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/README.md)**: Documents quick-start commands and the server lifecycle - **[`viewer/docs/backend.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/docs/backend.md)**: Details the query parameter handling for local asset serving - **[`viewer/src/client/components/StepViewer.tsx`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/src/client/components/StepViewer.tsx)**: React component that parses STEP files and manages the viewport interactions (rotate, zoom, pan) - **`viewer/src/server/localAssetBackend.test.mjs`**: Test suite verifying the local filesystem backend can serve STEP assets securely within the specified directory root The viewer restricts file access to the directory specified in `?dir=` for security, preventing traversal outside the designated model folder. ## Summary - **Install dependencies** by running `npm install` in the `viewer/` directory - **Start the server** using either `npm run dev` for manual control or `npm run agent:start -- --dir ` for automated port management - **Load STEP files** by appending `?dir=&file=` to the local URL - **Automate previewing** with the `$cad-viewer` skill to generate instant links without manual URL construction ## Frequently Asked Questions ### What file formats does CAD Viewer support? CAD Viewer primarily renders STEP (`.step` and `.stp`) files. The implementation uses hidden GLB topology side-cars for high-performance face and edge selection, while maintaining the original STEP parameter controls for precise geometric inspection. ### Can I run CAD Viewer without installing Node.js dependencies? No. The viewer requires Node.js and npm to install the Vite build system, React framework, and CAD runtime libraries. You must run `npm install` in the `viewer/` directory before starting the server, as documented in [`viewer/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/README.md). ### How does the agent mode differ from the standard development server? The **agent launcher** (`npm run agent:start`) automatically selects an unused port, caches the directory path for subsequent launches, and reuses an existing browser instance if the viewer is already running. The standard **dev server** (`npm run dev`) requires manual port specification and does not persist state between sessions. ### Why must the file path be relative to the directory root? The `?file=` parameter must be relative to the `?dir=` root for security containment. The backend implementation in `viewer/src/server/localAssetBackend.test.mjs` validates that requested files reside within the specified directory, preventing directory traversal attacks that could expose sensitive filesystem data outside your models folder.