# How to Configure CAD Viewer for Local Development with Custom Models

> Learn to configure CAD Viewer for local development with custom models. Set VIEWER_DEFAULT_DIR or use the ?dir= URL parameter for seamless integration. Get started now!

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-08-01

---

**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`.

```text
/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:

```bash
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:

```bash
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:

```bash

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

```bash
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:

```json
{"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:

```javascript
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:

```javascript
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.