How to Configure CAD Viewer for Local Development with Custom Models

You can configure the CAD Viewer for local development by setting VIEWER_DEFAULT_DIR to an absolute path containing your models and launching the dev server with npm run dev, or by passing the directory via the ?dir= URL parameter when accessing the Viewer in your browser.

The CAD Viewer in the earthtojake/text-to-cad repository provides a browser-based workbench for inspecting STEP, STL, GLB, URDF, SRDF, SDF, DXF, and G-code files without external hosting. To configure CAD Viewer for local development with custom models, you point the application at a local directory containing your files using environment variables, URL parameters, or the agent helper script. This setup allows rapid iteration on mechanical designs by serving files directly from your local filesystem through the Vite development server.

Prerequisites and Directory Setup

Before starting the Viewer, create or select an absolute directory path that contains your CAD files. The Viewer refuses relative paths and validates inputs through normalizeAgentDirectory in scripts/start-agent-viewer.mjs.

/home/user/my-cad-models/
├─ robot-arm.step
├─ gear.stl
└─ robot.urdf

Ensure the directory exists and contains supported formats. The Viewer reads files relative to this root directory when rendering models in the browser interface.

Configuration Methods

Method 1: Environment Variables and Dev Server

Set VIEWER_ASSET_BACKEND=local-fs to enable local filesystem serving, and optionally define VIEWER_DEFAULT_DIR to specify your models location:

export VIEWER_ASSET_BACKEND=local-fs
export VIEWER_DEFAULT_DIR=/home/user/my-cad-models
export VIEWER_DEFAULT_PORT=4178  # Optional, defaults to 4178

Install dependencies once, then launch the development server:

npm install
npm run dev -- --host 127.0.0.1

Vite launches on http://127.0.0.1:5173 (or another free port), automatically picking up VIEWER_DEFAULT_DIR if exported. The server mounts the local-FS backend defined in the Viewer configuration.

Method 2: URL Parameters for Dynamic Loading

Navigate to the running Viewer instance and append the ?dir= parameter with your absolute directory path. Optionally specify a particular file with ?file=:

http://127.0.0.1:5173?dir=/home/user/my-cad-models&file=robot-arm.step

The viewerConfig.mjs module processes these parameters through normalizeViewerDefaultFile and normalizeViewerGithubUrl to construct the final Viewer URL. This method overrides any VIEWER_DEFAULT_DIR setting and allows quick switching between different model sets without restarting the server.

Method 3: Agent Helper for Process Reuse

Use the agent helper script to automatically manage server instances and reuse existing processes. The helper resolves free ports, registers processes in viewerServerRegistry, and activates directories via the /__cad/directory/activate endpoint:

# First run - starts new dev server

npm run agent:start -- --dir /home/user/my-cad-models

# Subsequent runs - reuses existing process, switches directory

npm run agent:start -- --dir /home/user/other-models

The agentViewerUrl function in scripts/start-agent-viewer.mjs constructs the proper URL by concatenating the base address with the normalized directory parameter.

Technical Implementation Details

Directory Activation Workflow

When using the agent helper, the system implements a three-step activation process:

1. Server Detection: Queries /__cad/server to retrieve server information defined in viewerServerInfo.mjs, which advertises the JSON payload containing app, port, git, and dynamicRoot properties.
2. Port Resolution: If no server exists, resolves a free port (defaulting to 4178) and launches the Vite dev server or bundled production server.
3. Directory Activation: POSTs to /__cad/directory/activate to switch the active directory without process restart, enabling rapid iteration across multiple model repositories.

Production-Style Serving

For testing production builds locally, use the bundled server instead of the dev server:

npm run build          # Creates dist/

npm run serve -- --dir /home/user/my-cad-models --json

The src/server/server.mjs entry point handles the bundled assets. The --json flag outputs machine-readable metadata:

{"url":"http://127.0.0.1:4178?dir=/home/user/my-cad-models","port":4178,"action":"start"}

Programmatic API Examples

Activating Directories via Node API

Import activateAgentViewerDirectory from the agent script to programmatically switch directories on a running instance:

import { activateAgentViewerDirectory } from "./viewer/scripts/start-agent-viewer.mjs";

const baseUrl = "http://127.0.0.1:4178";
const directory = "/home/user/my-cad-models";

activateAgentViewerDirectory({ baseUrl, directory })
  .then(info => console.log("Activated:", info.viewerUrl))
  .catch(err => console.error(err));

Building Viewer URLs

Generate properly formatted URLs using the helper functions:

import { agentViewerUrl } from "./viewer/scripts/start-agent-viewer.mjs";

const url = agentViewerUrl("http://127.0.0.1:5173", "/home/user/my-cad-models");
console.log(url); // => http://127.0.0.1:5173?dir=/home/user/my-cad-models

Summary

• Use absolute paths when specifying model directories; relative paths are rejected by normalizeAgentDirectory.
• Set VIEWER_ASSET_BACKEND=local-fs to enable local filesystem serving mode.
• Access models via ?dir= URL parameter or pre-configure with VIEWER_DEFAULT_DIR environment variable.
• Reuse server processes using npm run agent:start to avoid port conflicts and enable rapid directory switching through the /__cad/directory/activate endpoint.
• Key source files: scripts/start-agent-viewer.mjs handles CLI logic, viewer/src/shared/viewerConfig.mjs manages URL normalization, and viewer/src/server/viewerServerInfo.mjs defines the server metadata structure.

Frequently Asked Questions

What CAD file formats does the Viewer support?

The CAD Viewer supports STEP, STL, GLB, URDF, SRDF, SDF, DXF, and G-code files. You can place any combination of these formats in your local directory and access them through the browser interface without conversion.

Can I use relative paths for the model directory?

No. The Viewer requires absolute directory paths for security and consistency. The normalizeAgentDirectory function in scripts/start-agent-viewer.mjs explicitly validates that paths are absolute and exist on the filesystem before serving content.

How do I switch between different model sets without restarting the server?

Use the agent helper with npm run agent:start -- --dir /new/path or programmatically call activateAgentViewerDirectory() with the new directory path. Both methods POST to the /__cad/directory/activate endpoint on the running server, switching the active directory instantly without process interruption.

What is the difference between npm run dev and npm run serve?

npm run dev launches the Vite development server with hot module replacement and debug features, ideal for active development. npm run serve starts the production server (src/server/server.mjs) using pre-built assets from the dist/ directory, suitable for testing production performance or serving static files in deployment scenarios.

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