How to Start and Configure CAD Viewer with the cad-viewer Skill

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, 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). If no instance is running, it spawns one using the npm script agent:start with the query string parameter ?dir=<absolute-model-root> 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.

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:

   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://<host>:<port>/?dir=<models-root>&file=<relative-path> 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.

• 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).

Create a .env file at the project root to override defaults:

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

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:

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:

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:

# 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 – Skill definition, contract, and handoff specifications.
• 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 – 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, 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, but you can redirect it to persistent storage like /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.

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