# How to Start and Configure CAD Viewer with the cad-viewer Skill > Learn to start and configure CAD Viewer with the cad-viewer skill. Use the agent launcher command and set environment variables in a .env file for easy setup. - Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) - Tags: how-to-guide - Published: 2026-07-29 --- **To start and configure CAD Viewer with the cad-viewer skill, execute the agent launcher command `npm --prefix scripts/viewer run agent:start` and set environment variables like `VIEWER_SERVER_REGISTRY` in a `.env` file at the repository root.** The `cad-viewer` skill in the `earthtojake/text-to-cad` repository provides the runtime interface for launching the CAD Viewer web application and handing off generated artifacts. Understanding how to properly initialize and configure this component is essential for integrating interactive 3D model previews into your CAD generation workflows. The implementation uses an agent-based process manager and environment-driven configuration as defined in the source code under `skills/cad-viewer/` and `viewer/`. ## Architecture Overview The **cad-viewer** skill architecture consists of a web-based viewer application and a management layer that handles process lifecycle. According to [`viewer/package.json`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/package.json), the package is explicitly named **"cad-viewer"** and contains scripts to bundle the skill runtime using `scripts/bundle/bundle-skill.sh cad-viewer`. When the skill receives a request to display a model, it checks for an existing **CAD Viewer** process via the **agent launcher** (documented in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md)). If no instance is running, it spawns one using the npm script `agent:start` with the query string parameter `?dir=` to specify the model directory. The system optionally supports a local MoveIt 2 server for interactive planning when `MOVEIT2_SERVER_REPO_ROOT` is configured. ## Starting CAD Viewer Follow these steps to initialize the viewer using the official agent launcher: 1. **Verify skill installation** – Ensure the `cad-viewer` skill is present in the repository under `skills/cad-viewer/`, which defines the skill contract and runtime behavior in [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md). 2. **Run the agent launcher** – Execute the npm command that manages the viewer process lifecycle. The launcher automatically reuses an existing instance if one is already active: ```bash npm --prefix scripts/viewer run agent:start -- \ --host 127.0.0.1 \ --shutdown-after 12h ``` This starts a persistent process bound to localhost that remains active for 12 hours or until manually terminated. 3. **Hand off CAD artifacts** – Skills that generate files (such as `urdf`, `step-parts`, `srdf`, or `sdf`) invoke the `$cad-viewer` service with the absolute file path. The skill returns a URL in the format `http://:/?dir=&file=` for immediate browser access. ## Configuration Options The **cad-viewer** skill loads environment variables from a `.env` file located at the repository root. Key variables include: - **`VIEWER_SERVER_REGISTRY`** – Specifies the JSON file path where active viewer server instances are tracked. Default value referenced in `viewer/.env.example` is [`/tmp/cad-viewer-servers.json`](https://github.com/earthtojake/text-to-cad/blob/main//tmp/cad-viewer-servers.json). - **`MOVEIT2_SERVER_REPO_ROOT`** – Absolute path to the MoveIt2 server repository, required only when enabling interactive planning features. Example value: `$(pwd)/moveit2_server` (see [`docs/moveit2-server.md`](https://github.com/earthtojake/text-to-cad/blob/main/docs/moveit2-server.md)). Create a `.env` file at the project root to override defaults: ```bash # .env VIEWER_SERVER_REGISTRY=/var/run/cad-viewer/servers.json MOVEIT2_SERVER_REPO_ROOT=/opt/moveit2_server ``` ## Implementation Examples ### Launching from the Command Line Start the viewer with specific host and shutdown parameters using the script defined in the viewer package: ```bash npm --prefix scripts/viewer run agent:start -- \ --host 127.0.0.1 \ --shutdown-after 12h ``` The double dash (`--`) separates npm arguments from the viewer arguments. ### Integrating with a Python Skill Skills can programmatically launch the viewer using the provided runtime interface: ```python from pathlib import Path from cad_viewer import launch_viewer urdf_path = Path("models/robot_arm.urdf") viewer_url = launch_viewer(str(urdf_path)) print(f"Open CAD Viewer: {viewer_url}") ``` ### Customizing the Server Registry To persist server metadata in a custom location rather than the temporary directory, set the registry path before starting: ```bash export VIEWER_SERVER_REGISTRY=/home/user/.cad-viewer/servers.json npm --prefix scripts/viewer run agent:start ``` ### Invoking from Other Skills via YAML Reference the viewer service in skill prompts to automatically hand off generated files: ```yaml # skills/urdf/skill.yaml default_prompt: | Generate the robot URDF using $urdf, then immediately pass the output file path to $cad-viewer for visualization. ``` ## Key Source Files The following files define the behavior and configuration of the viewer system: - [`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md) – Skill definition, contract, and handoff specifications. - [`viewer/package.json`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/package.json) – Package metadata and bundle scripts for the "cad-viewer" runtime. - `viewer/.env.example` – Template for environment variables including `VIEWER_SERVER_REGISTRY`. - `scripts/viewer/run-agent-viewer.test.mjs` – Test harness demonstrating agent launcher usage. - [`docs/moveit2-server.md`](https://github.com/earthtojake/text-to-cad/blob/main/docs/moveit2-server.md) – Documentation for optional MoveIt 2 server integration. ## Summary - Execute **`npm --prefix scripts/viewer run agent:start`** to launch or connect to a CAD Viewer instance, passing arguments after the double dash (`--`). - Configure persistent settings using a **`.env`** file at the repository root, specifically `VIEWER_SERVER_REGISTRY` for instance tracking. - The viewer supports **URDF**, **STEP**, **SDF**, and **SRDF** formats via the `$cad-viewer` service interface. - The agent launcher automatically reuses existing server instances to prevent port conflicts and redundant processes. ## Frequently Asked Questions ### How does the skill handle existing viewer instances? The **cad-viewer** skill maintains a registry of active servers in the JSON file specified by `VIEWER_SERVER_REGISTRY`. When starting, the agent launcher checks this registry and reuses an existing process if the host and port match, preventing duplicate viewer windows. ### What CAD file formats are supported by the viewer? According to the skill implementation in [`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md), the viewer accepts **URDF**, **STEP**, **SDF**, and **SRDF** files. Any skill generating these formats can hand off the absolute file path to the `$cad-viewer` service for immediate rendering. ### How do I change the location where viewer server information is stored? Set the **`VIEWER_SERVER_REGISTRY`** environment variable in your `.env` file or export it before running the agent launcher. The default location is [`/tmp/cad-viewer-servers.json`](https://github.com/earthtojake/text-to-cad/blob/main//tmp/cad-viewer-servers.json), but you can redirect it to persistent storage like [`/var/run/cad-viewer/servers.json`](https://github.com/earthtojake/text-to-cad/blob/main//var/run/cad-viewer/servers.json) as shown in `viewer/.env.example`. ### Can I use the CAD Viewer without the MoveIt 2 server? Yes, the **MoveIt 2** integration is optional. The viewer functions independently for model visualization. Only set `MOVEIT2_SERVER_REPO_ROOT` if you require interactive motion planning capabilities documented in [`docs/moveit2-server.md`](https://github.com/earthtojake/text-to-cad/blob/main/docs/moveit2-server.md).