Date: 2026-09-10

​
Install and set up Nova

Prepare a local environment, configure Nova securely, and launch it from the project you want to work on.

​
Requirements

Nova’s npm distribution requires Node.js 22.12.0 or later, npm, a Compass account or supported model-provider credentials, and a terminal that can access your project. On Windows, PowerShell is a native choice.

​
Install and verify the CLI

Install the official package globally. It registers both nova and compass; this course uses nova.

​
Run initial setup

Use the guided flow to configure authentication, consent, provider access, and local preferences:
Nova can use Compass-managed models, supported provider credentials, implemented OAuth flows, or custom endpoints registered through nova models. Do not place API keys in project files, prompts, NOVA.md, Git-tracked configuration, or shell history.

​
Start Nova in a project

Launch Nova from the repository directory so it can resolve the correct project root, instructions, configuration, commands, skills, memory, sessions, and files.
For a new project, initialise project-local Compass configuration:
Project configuration is stored under ./.compass; global user state is stored under ~/.compass as resolved for the operating system.

​
Configuration precedence

Nova resolves ordinary configuration from lowest to highest priority:
  1. Built-in defaults.
  2. Global configuration at ~/.compass/config.json.
  3. Project configuration at ./.compass/config.json.
  4. Environment variables.
  5. Command-line flags.
This supports a shared baseline, project-specific overrides, and temporary per-invocation choices.

​
Non-interactive use and maintenance

Use print mode for one-off scripts or CI-style reads:
Interactive sessions are preferable for normal engineering work because they support follow-up questions, approvals, slash commands, plan state, and visible tool progress. nova tools-rpc --stdio is an integration surface, not the standard interactive workflow. For health checks, run:
Use nova setup to reconfigure authentication or provider access, and nova update to check for updates. Logs can contain project-sensitive metadata, so inspect them before sharing.
Nova’s uninstall flow may preserve or remove user data under ~/.compass. That location can contain configuration, encrypted credentials, sessions, memory, commands, agents, skills, usage data, and caches, so do not delete it casually.

​
What you learned

  • Nova needs a supported local runtime and secure provider setup.
  • The directory where you launch Nova establishes its project scope.
  • Configuration uses an explicit precedence order.

​
Safe practice exercise

In a disposable project, run nova --help and nova doctor. Do not add credentials to repository files.

Previous: How Nova works

Return to lesson 2.

Next: Your first Nova session

Continue to lesson 4.