How to Preview STEP Files Locally with CAD Viewer: A Complete Setup Guide

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.

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:

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, 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:

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:

npm run agent:start -- --dir /absolute/path/to/models

According to 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:

# 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. When invoked from another skill, it ensures the viewer is running and returns a markdown link:

$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: Documents quick-start commands and the server lifecycle
• viewer/docs/backend.md: Details the query parameter handling for local asset serving
• 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 <path> for automated port management
• Load STEP files by appending ?dir=<absolute-path>&file=<relative-path> 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}