Development Environment Setup
Setting up a Nimi development environment lets you build and debug local-first AI applications, test native host interactions, and run end-to-end user workflows on your machine.
Start by choosing an @nimiplatform/app-tools version that matches your target Nimi host, and stick to the dependency set it declares. In the current source repository, App Tools 0.14.0 scaffolds projects with SDK ^0.22.2, Kit ^0.22.1, and nimi-shell-tauri 0.11.1. Keep source declarations separate from npm releases: versions declared in this repository are not necessarily published to npm yet, and published packages do not include unreleased changes from source.
1. Required Toolchain
Make sure the following tools are installed on your machine:
- Node.js: Node.js 24.22.1 or a newer patch/minor release on the Node 24 LTS line.
- pnpm: pnpm 10.34.7 (or a compatible pnpm 10.x release).
- C/C++ Build Tools (optional): If compiling Kit's optional native extensions from source, install Xcode Command Line Tools on macOS or Visual Studio C++ build tools on Windows.
Scaffolded app projects include project-local Nimi Coding pinned by your chosen App Tools package (0.7.0 in the App Tools 0.14.0 source scaffold). Run pnpm install && pnpm run init to configure it without installing a global binary.
2. Core Dependency Combinations
Nimi's core packages are versioned independently, and each App Tools release declares a matching dependency set. Choose versions based on how you install:
- From npm: Use the dependency combination generated by your published
@nimiplatform/app-toolsrelease. - From current source: The App Tools
0.14.0source scaffold declares the following combination:
| Package | Source Scaffold Version | Role |
|---|---|---|
@nimiplatform/sdk | ^0.22.2 | Client core API, AI inference, and host-bound session integration |
@nimiplatform/kit | ^0.22.1 | Cross-platform UI components, window bridge, and theme contracts |
@nimiplatform/app-tools | ^0.14.0 | App scaffolding, project initialization, and production packaging |
nimi-shell-tauri | 0.11.1 | Tauri shell pinned by the scaffold |
@nimiplatform/sdk-adapter-vercel-ai | ^0.6.2 | (Optional) Adapter for Vercel AI SDK 7 |
Unreleased APIs added in source require a matching source build—do not expect unpublished source capabilities in npm releases, and do not try to enable them in a standalone app by changing version strings alone. When working with unreleased source changes, follow the source-workspace workflow in ONBOARDING.md.
Local Archives & Overrides
For a standalone App testing locally built packages, select the complete .tgz archives with pnpm-workspace.yaml overrides. See Create a Nimi App for configuration details.
3. Local Development in Three Steps
If you are developing from the Nimi source repository, first complete the repository setup, including Go, native build tools, and environment settings. The source Runtime launcher connects to a separately prepared Realm service at http://127.0.0.1:3002; these commands do not start Realm. Then keep the following three processes running:
Step 1: Start the Local Runtime Service
In the root directory of the Nimi repository:
pnpm dev:runtimeThis runs the local user-space Runtime supervisor, providing unified local model dispatch, secure credential storage, and session authentication.
Step 2: Start Nimi Desktop / Home
In a second terminal window:
pnpm dev:desktopWhen the desktop window launches, sign in with your Nimi account to open Nimi Home. Open Settings → Developer and enable Developer Mode before launching your app. Make sure to also verify that your app's Nimi Access is ready separately.
Step 3: Launch Your App
In your application project directory:
pnpm devYour app will launch inside a Desktop-supervised window and request a protected session with the local Runtime. You can now test AI features, configure routing, and inspect responses.
4. Troubleshooting and Downloads
- Encountering service connection errors or missing permissions? Visit the Troubleshooting Guide.
- Looking for ready-to-run desktop installers for daily use? Visit the Official Downloads Page.