Quickstart

Requirements

The workspace declares Bun 1.4.4 as its package manager. Use the repository lockfile for dependency installation. Native desktop development also requires a Rust toolchain, the platform's Tauri build dependencies, and an installed system webview. The Tauri CLI is already a desktop development dependency.

• macOS: Xcode command-line tools for Rust/native linking and packaging.
• Windows: the MSVC toolchain and WebView2 runtime/build prerequisites.
• Linux: WebKitGTK 4.1, application-indicator, librsvg, OpenSSL, and bundler tools. The CI workflow records the packages used on Ubuntu.
• iOS companion: macOS, Xcode, CocoaPods, and a native Expo build containing the local pinning module.

A browser preview requires Bun and workspace dependencies but does not compile the Rust shell. A release installer additionally requires signing configuration; that is separate from local UI development.

Install dependencies

bun install
bun run --filter @cadcamfun/desktop typecheck
bun test packages/core

Install once at the workspace root so local workspace:* dependencies resolve together. CI uses bun install --frozen-lockfile to reject lockfile drift. Use the package scripts to select the repository's configured compiler rather than assuming every package uses the same TypeScript executable.

The targeted commands above provide a quick source check. The full workspace checks are bun run typecheck and bun run test; they cover more modules and may take longer. An individual passing package does not prove all runtime integrations are configured.

Database setup

The real desktop does not require a separate CLI migration command. Its launcher supplies the application data directory and staged migrations to the sidecar; opening the database applies pending migrations. bun run desktop:dev stages the migration resource as part of preparing the sidecar.

The database command-line tool is separate. bun run db:migrate delegates to the database package and defaults to ./data/cadcamfun.db relative to that package's process directory, normally packages/db/data/cadcamfun.db when invoked through the root script. Set an absolute DATABASE_URL when you need to target a specific database.

bun run db:generate
bun run db:migrate

Generation reads packages/db/src/schema.ts and writes migrations under packages/db/drizzle. Applying migrations updates the selected CLI database, not every application database. Native desktop data lives in the Tauri application data directory; a manually started sidecar uses CADCAMFUN_DATA_DIR.

Open the desktop

bun run desktop:dev

This compiles the real Bun sidecar and stages migrations, then runs Tauri. Tauri starts Vite at http://localhost:1420 and opens the webview. The Rust shell waits for the sidecar's ready handshake; the webview checks health before showing routed screens.

Keep the launching terminal open. The shell owns the sidecar lifecycle and supplies its launch token and paths. If startup fails, inspect the boot reason and application logs. The webview retries endpoint discovery for up to 150 seconds; the shell permits one automatic sidecar restart.

bun run --filter @cadcamfun/desktop dev

Open http://localhost:1420. With no VITE_SIDECAR_URL, this uses the in-memory fake API. It supports a subset of requests and does not provide persistent projects, provider sessions, or native dialogs. Connect to a live sidecar by setting both Vite sidecar URL and token process variables.

The desktop package's tauri:dev script creates a stub sidecar when the binary is missing. The stub supports shell isolation. Prefer the root desktop:dev command when exercising application services.

bun run desktop:dev first runs build:sidecar, which compiles the sidecar and stages migrations (pipeline steps compile and resources). It then starts tauri dev in the desktop package.

Verify the first session

1. Wait for the application to leave the boot screen and confirm it is connected to the intended API.
2. Create or open a project and enter CAD or CAM.
3. Save the work and reopen it through the project/resource UI to verify persistence.
4. If using the assistant, configure a supported model provider in desktop settings before starting a conversation.
5. If using the iOS companion, enable its gateway and create a device pairing on the desktop.

Testing a visible path does not validate machining safety. Inspect stock, tooling, machine limits, post output, and verification results for the actual operation before transferring NC output to a machine.

bun run --cwd packages/web start
bun run --cwd packages/web check
bun run --cwd packages/web build

The web start command runs Astro. Use its printed local address. The web dev script additionally starts the Studio API, which can open the selected local database; use it when working on Studio rather than static documentation alone.

Next commands

Verify a real API without a model

Start the manual sidecar described in the local development guide, or use the endpoint/token of a development process you control. The following recipe creates one disposable project and lists it. It needs curl; the optional identifier extraction uses Bun. Replace the example port and token with those of your isolated sidecar.

CADCAM_URL=http://127.0.0.1:43111
CADCAM_TOKEN=local-development-token

curl --fail-with-body "$CADCAM_URL/api/health"

curl --fail-with-body -X POST "$CADCAM_URL/api/projects"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"name":"Documentation smoke","description":"Disposable local check","isPublic":false}'   -o /tmp/cadcamfun-project-smoke.json

curl --fail-with-body "$CADCAM_URL/api/projects"   -H "Authorization: Bearer $CADCAM_TOKEN"

CADCAM_PROJECT_ID=$(bun --no-env-file -e   'const row = await Bun.file("/tmp/cadcamfun-project-smoke.json").json(); console.write(row.id)')
curl --fail-with-body "$CADCAM_URL/api/projects/$CADCAM_PROJECT_ID"   -H "Authorization: Bearer $CADCAM_TOKEN"

Health returns a status/timestamp object. Project creation returns HTTP 201 and a project row with its identifier. Listing returns an array of projects with owner/organization relations and counts; reading by identifier returns one such related project. The example does not call a model or generate machine output.

Close the manual sidecar cleanly, restart it with the same data directory, update the ephemeral URL, and list projects again to check persistence. A new launch may choose a different port. If this project is absent, first compare the data directory, client endpoint, and authorization context.

Cleanup is optional and destructive for this one disposable project: send DELETE /api/projects/<id> only after confirming the returned identifier. Creation/list/read exercise application persistence without requiring cleanup to succeed.

Interpret first-run failures

Keep the first verification small: health, one project, one persisted drawing/program, then optional integrations. A successful base application launch does not configure Stripe, AI providers, a remote GitHub repository, or mobile routing automatically.

Requirement details

Your first hour, step by step

git clone https://github.com/nikomatt69/cadcamfun.git
cd cadcamfun
bun install --frozen-lockfile
bun run typecheck                 # all workspaces
bun run test                      # bun test packages apps scripts
bun run desktop:dev               # builds the sidecar + migrations, then tauri dev

1. When the window opens, the sidecar status turns ready within seconds; a new data directory is migrated on first launch.
2. Create a project, add a drawing, draw a rectangle and extrude it.
3. Open CAM, pick the solid and generate. Check the release level and claims before exporting NC.
4. Open the history panel and commit: the project now has its first version.

In 3D