First Run

When you launch Nous for the first time, you'll see a guided flow that helps you get started.

First-Run Flow

1. Welcome — Introduces Nous and what just happened during installation.
2. Identity — Name your agent, optionally choose a personality, and optionally tell Nous a little about yourself. Three short sub-steps: Naming → Personality → Profile. See the Identity guide for details.
3. Ollama Setup — Confirms a local Ollama is reachable and ready (or routes you through installing one).
4. Model Download — Pulls the recommended local model and assigns it to the four core agent roles in one step. See The Model Download Step for the validation indicator and auto-role-assign behaviour.
5. Confirmation — Confirms everything works and hands you off to the workspace.

You can press Back at any step to return to the previous one. From the Identity step, Back returns you to Welcome.

When you open the chat panel for the first time after finishing the wizard, the agent emits a one-shot welcome message in the personality preset you chose. The welcome message appears in the chat UI on first chat open regardless of which chat surface you use, is durable across re-mount (closing the chat and reopening it shows the same single welcome, not a duplicate), and is not re-issued once the welcome has already been sent. The welcome appears as a normal agent message; nothing else about the chat looks different. Your chosen agent name, personality preset, and profile fields shape every reply on the principal chat from the first chat turn onward — not only the welcome. See Welcome Message (First Open) for the full lifecycle and reset semantics.

The Identity Step

The Identity step is where the agent becomes yours. It's split into three sub-stages with a short fade between them:

• Naming — Pick a name for your agent (defaults to "Nous"). The submit button enables once the field is non-empty. There is no Skip on Naming — every agent has a name.
• Personality — Choose one of the four presets (balanced, professional, efficient, thorough), optionally open Advanced Options to override individual trait axes (thoroughness, initiative, candor, communicationStyle, codeStyle). You can also press Skip to keep the default balanced preset and move on.
• Profile — Optionally tell Nous your display name, role, primary use case, and expertise level. A short security disclosure explains that this stays local, is used only to personalize Nous's behavior, and is never sent externally without an explicit action on your part. Skip sends an empty profile and continues.

Submit on Profile (or Skip) writes the full identity payload — { name, personality, profile } — to your config in a single batched call. Backend completion of agent_identity is recorded only after Profile submits or skips, never partway through.

If your operating system has Reduce motion enabled (prefers-reduced-motion: reduce), the fade between sub-stages is suppressed and sub-stage swaps happen instantly. Navigation is identical — only the visual transition changes.

For the full walkthrough of preset semantics, advanced overrides, the security disclosure, and the underlying schema, read the Identity guide.

The Model Download Step

The Model Download step is where Nous picks a local model that fits your hardware, pulls it through Ollama, and wires it up to the four core agent roles. You see one or more recommendation cards sized to your machine, plus a custom model spec input if you want to override the recommendation.

Why these models? Hardware-to-recommendation summary

Above the recommendation cards, the wizard shows a short hardware summary that explains how the recommendations were chosen. It surfaces the RAM (in GB), CPU core count, and GPU presence (and name where available) that Nous detected on your machine, the tier that Nous mapped those specs to (Compact, Balanced, Mid-spec, or High-spec), and the per-tier model titles those specs map to. The hero subtitle reads: "Recommendations are tailored to your detected hardware. Adjust below if needed." This makes the link from your hardware to the cards below explicit, so you can answer "why these models?" without reading source code. The summary is omitted when no local hardware profile is available (for example, in a remote-only configuration).

Recommendation cards and the validation indicator

Each recommendation card carries a small validation indicator that tells you whether Nous can currently pull that model from the public Ollama library. The indicator has four states:

All four states remain selectable. The Download button is never gated by the validation state — Nous biases toward letting you try the download even when verification is uncertain, because Ollama's local cache may already have the model and registry coverage may differ between the wizard process and the Ollama daemon. If a download ultimately fails, the wizard surfaces the underlying Ollama error message in place.

If a recommended model is already pulled locally (visible to your Ollama daemon), Nous renders its card as validated directly, regardless of whether the registry HEAD probe succeeds. Local presence is durable signal — being offline, behind a captive portal, or rate-limited by the Ollama registry will not cause an installed model to display as unavailable or offline. The registry probe still runs for models you do not yet have, exactly as before.

The validation check runs once at step mount, not on every keystroke or click. Nous keeps a 30-minute per-spec session cache so navigating back to the step does not re-issue probes. Locally-present models short-circuit the probe entirely and do not consume a cache entry.

Custom model spec

Below the recommendation cards there is an input where you can type any Ollama spec (for example ollama:llama3.3:70b or ollama:mistral-small:24b). The input itself does not validate as you type. When you press Download, Nous validates the entered spec against the registry once and then proceeds with the pull.

If you submit a spec that is malformed (empty, missing the ollama: prefix, or pointing to a non-Ollama provider) the validation indicator next to the input shows Not currently available and the download is not attempted.

Privacy posture for the validation check

The availability check is an anonymous HEAD request to https://ollama.com/library/<model> with only Accept: */* and a generic User-Agent: Nous/<version> header. Nothing identifying about your machine is sent: no OS string, no architecture, no CPU or GPU details, no user identifier, no session identifier, no device identifier. The model identifier is the only request-shape information leaving your machine, and it is the same string Ollama would request for the actual pull.

Auto-role-assign

When the download succeeds, Nous assigns the downloaded model to all four core agent roles in one step — cortex-chat, cortex-system, orchestrators, and workers — using the model spec you just downloaded. There is no separate "role assignment" screen anymore; the wizard goes model-download → confirmation directly.

You can change individual role assignments later from the Configuration panel without re-running the wizard.

Skipping the model download

Pressing Skip on this step leaves the model role assignments unchanged and advances the wizard. This is useful when you already have a configured model from a prior run, or when you intend to wire up cloud providers manually before assigning roles. The step's three backend completion markers (model_download, provider_config, role_assignment) are all marked complete on skip — the agent reaches the workspace, but you are responsible for assigning models before chat will produce useful output.

Reduced motion

If your operating system has Reduce motion enabled, the validating-state amber dot stops pulsing. The dot still renders and the label still updates; only the animation is suppressed.

Skipping First Run

If you already have projects or have completed the first-run flow before, Nous redirects you directly to the chat page.

What Gets Configured

During first run, Nous generates and persists:

• Default config — Cortex tier 3, Ollama as the default provider for all four model roles.
• Storage — SQLite database in your data directory.
• Projects — Empty; create your first project from the sidebar.
• Agent identity — Your name, personality, and profile choices land in the agent block of nous-config.json5. Skipping any step keeps the typed defaults ("Nous", { preset: "balanced" }, {}) until you decide otherwise. A welcomeMessageSent: boolean field is also persisted; it flips to true after the agent's first welcome message lands in chat, and clears back to false on firstRun.resetWizard so a fresh first-run experience always re-fires the welcome. See Configuration Schema § Agent.

You can adjust model assignments and Cortex tier later in the Configuration panel. To re-run the wizard from scratch (clearing the entire agent block while leaving providers and role assignments intact), call the firstRun.resetWizard mutation — see tRPC Procedures § firstRun.