First-success onboarding

Holaryn opens a supported onboarding path when the current state directory is unconfigured or has onboarding in progress. An existing installation that already has an authenticated default chat model is not interrupted merely because it predates onboarding.json. The same progress is available at /onboarding in the desktop/web UI and through holaryn onboard in a terminal. Every completed step is written to onboarding.json in the state directory, so closing the app, restarting the host, or interrupting the CLI resumes at the first unfinished step.

Onboarding has one job: prove that Holaryn can receive a real model response and execute an explicitly approved tool action safely. It does not configure every optional feature.

Desktop path

Launch the desktop app normally. A fresh installation opens the first-success flight plan instead of dropping you into an unconfigured chat. In the desktop app, choose Help → First-time Setup… to resume or review the same wizard later. This menu command only opens the saved onboarding state; it does not reset settings, credentials, progress, or work. You can also open it at http://127.0.0.1:8765/onboarding.

Begin explains what setup changes and what it will not touch.
Connect embeds the production Providers & Models controls. Pick a catalog provider, sign in or enter its key, scan models, and make an enabled chat model the default. Authentication and scans use the same paths as Providers & models; onboarding does not maintain another provider configuration.
Assign recommends initial general, coding, vision, and embedding roles from the default model, tags, advertised capabilities, and modality. General and coding are needed to start. Vision and embedding remain visibly unassigned when no suitable model exists.
Protect offers only ask and selective, the two conservative attended postures. Broader postures remain in Autonomy & approvals behind their normal confirmation ceremony.
Answer sends a fixed tool-free verification prompt through the selected production provider. The response is displayed as its provider chunks arrive.
Act prepares one write_file call under the generated onboarding-demo directory. The call stays parked until you approve the displayed target and diff. Deny runs no tool. Undo demo file removes only the known generated file.
Ready records completion and opens Chat.

The left progress rail becomes a swipeable step strip on a narrow window. Completed steps can be revisited. Open chat without finishing bypasses onboarding for that page load; it does not claim setup succeeded, so the supported path remains available on the next ordinary launch.

CLI path

Run the guided driver. It starts at the first unfinished step, saves after every
step, and exits at the first repair that needs your attention:

holaryn onboard start

The driver chooses the provider interactively, accepts the initial role
recommendations, asks for an attended autonomy posture, streams the fixed
verification response, requests explicit approval for the generated demo, and
records completion. Rerunning it after completion changes nothing.

Use holaryn onboard status to report the first incomplete step, structured
readiness diagnostics, and the exact repair command. --json returns the same
non-secret state and diagnostic contract used by the UI.

The equivalent step-by-step sequence, useful for automation or repair, is:

holaryn onboard configure
holaryn onboard roles
holaryn onboard posture selective
holaryn onboard verify
holaryn onboard demo
holaryn onboard undo-demo       # optional, but proves rollback
holaryn onboard complete

configure shows the same provider catalog. API keys are requested through hidden input; there is deliberately no --api-key argument that would leak a credential into shell history or the process list. You can make a reproducible non-secret selection with --preset, --connection-id, --model, and --base-url. Subscription connections are saved first, then the CLI tells you to run holaryn connection login <id> and resume configuration.

verify prints model chunks as they arrive and times out with a repairable error if the provider never finishes. demo describes the exact generated target and waits for a y/yes approval. A denial writes nothing. Progress survives either outcome.

Use a different state directory by placing the option before the subcommand:

holaryn onboard --state-dir D:\holaryn-state status

holaryn onboard reset resets onboarding progress but keeps provider settings and credentials.

To return the entire local configuration to defaults, use Settings > Advanced > Reset Holaryn
instead. That separate, typed-confirmation flow removes local settings and credentials while
preserving chats, memory, files, artifacts, logs, audit evidence, and task history. Restart Holaryn
afterward; this onboarding path opens automatically against the reset configuration.

Docker, source, and offline paths

All supported activation paths use the same state machine and recovery contract:

Docker Compose: run python deploy/compose/manage.py up, follow the
authenticated URL printed by the manager, and open /onboarding. Compose
keeps the state volume across container replacement.
Source checkout: run uv sync, then uv run holaryn onboard start.
Offline or portable: prepare an existing Ollama or GGUF runtime with
holaryn local-model diagnostics, then choose that keyless local provider in
onboarding. Telemetry is not required.

The desktop path needs no terminal or configuration-file editing. Package,
source, and Compose operators can use the guided CLI or the same /onboarding
UI.

What is recorded

onboarding.json contains only:

completed step names;
selected registry model ids and the safe posture;
demo lifecycle state;
elapsed milliseconds to the first successful response and first successful tool call; and
update/migration metadata, the completion flag, and schema version.

It never contains API keys, OAuth bundles, prompts, model responses, tool output, absolute paths, account ids, or provider payloads. Verification errors pass through a bounded credential redactor before reaching UI or CLI diagnostics. The normal write-only secret store remains the only durable credential location.

Diagnostics and repair

Readiness checks use stable diagnostic codes such as connection_missing,
default_chat_model_missing, credential_missing,
provider_endpoint_invalid, state_corrupt, state_version_incompatible,
and state_unavailable. Verification failures classify authentication,
unreachable endpoints, capability mismatches, timeouts, and empty responses.
Each failure has one primary diagnosis plus a focused UI link and/or exact CLI
repair command. Common repairs are:

return to Connect when no provider/default model exists;
finish holaryn connection login <id> for a subscription connection;
correct the endpoint or credential, then rerun model scan and verification; or
start the host with a writable state directory if progress cannot be saved.

Schema-1 progress migrates in place. A malformed record or one written by a
newer incompatible Holaryn version is preserved and never silently replaced.
Choose Reset onboarding progress only or run holaryn onboard reset after
reviewing the diagnosis. Reset never deletes providers, models, credentials, or
unrelated settings.

Optional setup after first success

The Ready screen links to browser runtime repair, local voice, Telegram
messaging, and local-model management only after the first response and approved
tool use succeed. These features are not prerequisites:

holaryn browser repair
holaryn memory install-extra voice
holaryn local-model diagnostics

← Previous Mobile supervision Next → Organization governance