How to Start a New Instance of the CAD Viewer in text-to-cad

Use the cadgen viewer --new command from your target directory to force a fresh instance, or run npm run dev in apps/viewer to launch a development server with hot reload.

The text-to-cad repository by earthtojake combines a React frontend with a Python backend to provide an interactive CAD Viewer for local directories. Starting a new instance requires understanding the instance reuse logic that checks the current working directory and a version-derived identity token before binding to an available port.

Understanding the CAD Viewer Architecture

The CAD Viewer is split into two components: a lightweight React client and a Python backend provided by the cadgen.viewer package. Each instance serves exactly one directory—identified by its real path—and is managed by a launcher that decides whether to attach to an existing server or spawn a new one.

The decision logic resides in [packages/cadgen/src/cadgen/viewer/main.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/viewer/main.py#L1-L34). When you invoke the viewer, the launcher checks for a running instance matching the current directory's real path and the version-derived identity token. If a match exists, it reuses that server; otherwise, it initializes a new one on the first available port greater than or equal to 3245. For the full launch contract, see the viewer README.

Starting a New Instance

To explicitly create a fresh server rather than attaching to an existing one, append the --new flag to your command. This bypasses the reuse check and initializes a new Python backend immediately.

cd /path/to/models
cadgen viewer --new --host 127.0.0.1 --json

The --json flag outputs machine-readable JSON containing the url and port, enabling easy integration with automation scripts.

Development Mode with Vite

For active development, navigate to apps/viewer and use the Vite development server. According to the CLI implementation, this mode spawns a temporary Python backend on an ephemeral port and proxies API routes—including /__cad and /__tess_cache—to it automatically.

cd apps/viewer
npm run dev -- --host 127.0.0.1

The dev server compiles the React client on-the-fly—entry point at [apps/viewer/src/client/main.jsx](https://github.com/earthtojake/text-to-cad/blob/main/apps/viewer/src/client/main.jsx)—and launches the backend without requiring a prior build step. Access the viewer at http://127.0.0.1:5173/?file=<relative-path>.

Production Mode

For production, first build the static client bundle defined in [apps/viewer/package.json](https://github.com/earthtojake/text-to-cad/blob/main/apps/viewer/package.json), then launch the viewer from the directory containing the built assets:

cd apps/viewer
npm run build
cd /path/to/serve
cadgen viewer --host 127.0.0.1

The cadgen CLI serves the pre-built dist/ folder generated by the build command. The viewer binds to the first free port ≥ 3245 and prints the accessible URL upon startup.

Managing Running Instances

You can inspect and terminate viewer processes using the CLI subcommands.

• List instances: cadgen viewer list displays all currently running servers and their ports.
• Stop an instance: cadgen viewer stop --port <n> terminates the server listening on the specified port number.

These commands allow you to clean up stale processes before starting a new instance with specific port requirements.

Summary

• The CAD Viewer combines a React frontend and Python backend, serving a single directory per instance.
• Instance uniqueness is determined by the real path of the working directory and a version-derived identity token as implemented in main.py.
• Use cadgen viewer --new to force a fresh instance and bypass the reuse logic.
• Development uses npm run dev in apps/viewer to enable hot reload and temporary backend spawning via Vite.
• Production requires running npm run build first, then executing cadgen viewer from the target directory.
• Manage running servers with cadgen viewer list and cadgen viewer stop --port <n>.

Frequently Asked Questions

How do I force a new CAD Viewer instance if one is already running?

Execute cadgen viewer --new from the directory you want to serve. This flag instructs the launcher to ignore any existing instance matching the current directory and create a fresh Python backend on the next available port.

What port does the CAD Viewer use by default?

The viewer automatically selects the first free port greater than or equal to 3245. You can override this behavior by passing the --port argument with your desired port number.

Can I run the CAD Viewer from any directory?

Yes. The viewer serves the current working directory where the command is executed. For development, you must run npm run dev from apps/viewer. For production, run cadgen viewer from the directory containing your CAD files (and the built dist/ folder if serving locally).

How do I stop a running CAD Viewer instance?

Use the command cadgen viewer stop --port <n>, replacing <n> with the port number displayed when the server started. Alternatively, use cadgen viewer list to identify active ports before terminating them.

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