[RFC] ov setup — Interactive guided setup wizard for OpenViking

[ZaynJarvis]

Motivation

Getting started with OpenViking today requires reading docs, manually editing config files, and running multiple admin CLI commands in the right order. New users have no way to validate their configuration is correct without trial and error. This RFC proposes an ov setup interactive wizard that guides users from zero to a working, verified OpenViking environment.

Pain Points (from real usage)

1. No config validation or guided flow — users have no "config card" or step-by-step wizard; they must piece things together from docs.
2. Local model download is hidden — OpenViking supports using open-source embedding and VLM models, but this isn't surfaced during onboarding and common users don't know where to download.
3. Setup should be a utility, not core — ov setup should live as an extra utility command (like rustup or gh auth login), not bloat the core CLI.
4. No compatibility benchmark — users don't know which models (cloud and local) work well with OpenViking.
5. No install or remote connection detection — the CLI doesn't detect whether OpenViking server is running, offer to install it, or offer a remote domain+API key option.
6. Account/user setup is manual — creating accounts and users with root_api_key requires multiple ov admin commands and edits on ovcli.conf for API Key change
7. No smoke test — after setup, users must manually verify everything works.

Proposed ov setup Flow

ov setup

Step 1: Detect or Install OpenViking Server

🔍 Checking for OpenViking server...

[ ] Local server detected at http://localhost:1933
  OR
[ ] No local server found. Choose an option:
    (1) Install OpenViking locally (docker-compose)
    (2) Connect to a remote OpenViking instance
        → Enter server URL: ___
        → Enter API key: ___

• If local install chosen: pull the Docker image, generate ov.conf, start the container.
• If server is found but not running: offer to start it.

Step 2: Root API Key

🔑 Root API Key Setup

[ ] Enter your root_api_key: ___
  OR
[ ] Auto-generate a secure root_api_key? (Y/n)
    → Generated: ovk_xxxxxxxxxxxxxxxx
    → Saved to ~/.openviking/ovcli.conf

All subsequent admin operations in the wizard use this key.

Step 3: Account & User Setup

👤 Account Setup (using root_api_key)

  Account ID [default]: ___
  Admin user ID [admin]: ___
  → Created account "default" with admin user "admin"
  → API key for admin: ovk_yyyyyyyyyyyy

  Register additional users? (y/N)

This wraps the existing ov admin create-account and ov admin register-user commands.

Step 4: Model Configuration (Optional)

🤖 Model Setup

  Choose embedding model:
    (1) Cloud: OpenAI text-embedding-3-small
    (2) Cloud: Volcengine Doubao Embedding
    (3) Local: Download bge-m3 (ONNX, ~600MB)
    (4) Local: Download bge-large-en-v1.5
    (5) Custom endpoint

  Choose VLM model:
    (1) Cloud: OpenAI gpt-4o-mini
    (2) Cloud: Volcengine Doubao
    (3) Local: Download MiniCPM-V
    (4) Custom endpoint

  Downloading bge-m3... ████████████████ 100%

Step 5: Compatibility Benchmark (Optional)

📊 Run compatibility benchmark? (Y/n)

  Testing embedding model... ✅ bge-m3 (dims=1024, latency=12ms)
  Testing VLM model...       ✅ gpt-4o-mini (latency=320ms)
  Testing rerank model...    ✅ bge-reranker-v2 (latency=45ms)
  Testing vector store...    ✅ VikingDB (write=8ms, search=15ms)

  ┌──────────────────────────────────────────────┐
  │ Compatibility Report                         │
  ├──────────────┬───────────┬───────────────────┤
  │ Component    │ Status    │ Details           │
  ├──────────────┼───────────┼───────────────────┤
  │ Embedding    │ ✅ Pass   │ bge-m3, 1024d     │
  │ VLM          │ ✅ Pass   │ gpt-4o-mini       │
  │ Rerank       │ ✅ Pass   │ bge-reranker-v2   │
  │ VectorDB     │ ✅ Pass   │ VikingDB local    │
  └──────────────┴───────────┴───────────────────┘

Step 6: Smoke Test

🧪 Running quick verification...

  [1/4] Health check...          ✅
  [2/4] Add test resource...     ✅ (added "Hello OpenViking" doc)
  [3/4] Semantic search test...  ✅ (found doc, score=0.95)
  [4/4] Cleanup test data...     ✅

  ✨ OpenViking is ready! Try:
    ov add-resource ./my-docs --to viking://resources/docs
    ov find "search query"
    ov chat

Existing CLI Features That ov setup Would Wrap

From reading the current ov_cli crate:

Existing Command	Used in Setup Step
ov health / ov system health	Step 1 (detect server), Step 6 (smoke test)
ov config show / ov config validate	Step 2 (config validation)
ov admin create-account	Step 3
ov admin register-user	Step 3
ov observer models	Step 5 (benchmark)
ov add-resource	Step 6 (smoke test)
ov find	Step 6 (smoke test)
ov rm	Step 6 (cleanup)

What's New vs. What Exists

Feature	Status
Server health detection	✅ Exists (ov health)
Config file read/write	✅ Exists (Config::save_default())
Admin account/user creation	✅ Exists (ov admin subcommands)
Observer model status	✅ Exists (ov observer models)
Interactive prompts/wizard	❌ New — needs TUI or dialoguer integration
Server install/start	❌ New — docker-compose orchestration
Local model download	⚠️ Partially exists server-side, not CLI-exposed
root_api_key generation	❌ New — crypto key gen exists but not wired to setup
Compatibility benchmark	❌ New — model latency/dimension testing
Smoke test	❌ New — end-to-end add→search→cleanup

Implementation Notes

• Separate binary or subcommand: Could be ov setup (subcommand) or ov-setup (separate binary). Given the "utility, not core" principle, a separate binary in the same crate workspace might be cleanest.
• Interactive prompts: Use dialoguer crate for cross-platform terminal prompts.
• Config generation: Extend Config::save_default() to accept wizard-collected values.
• Docker integration: Shell out to docker compose for local install path.
• Model download: Expose the server's model download capability through a CLI command or direct download.

Open Questions

1. Should ov setup be a subcommand or a separate binary (ov-setup)?
2. Should the compatibility benchmark matrix be maintained in-repo or fetched remotely?
3. Should ov setup support non-interactive mode (ov setup --auto) for CI/scripting?
4. What's the minimum set of models to bundle for an offline-first local setup?

[ZaynJarvis]

origin prompt:

I found pain points when using this openviking.

1. I never know if my configuration is fine, and there's no recommended "config-card" so i can follow the steps, without docs, and just use ov command to finish the setup
2. I know there's a way to download opensourced embedding and vlm models, it should be an option in ov setup
3. ov setup should be an extra utility, not a core feature
4. and a compatibility benchmark should be released with ov setup, showing that many models, cloud and local, can work with ov setup
5. detect whether open-viking is installed, if not prompt to install it or use a remote domain with APIKey. if to install it or it's not running and try to run it. then you should
   prompt user for API key or random-gen root_api_key, then use it for step 5.
6. setup account and user with root_api_key all in setup step.
7. also ov setup should handle admin stuff, when trying to use admin API, always prompt for root_api_key, so to setup account and users
8. and setup should ask user whether to run a simple test show if it success. (so user don't have to do it themselves)

ingest what i want, read for repo for is there possibly already existed features, then use ghcli to submit a discussion to origin for adding ov setup command to do these things to
solve these pain points.

you should read and understand correct rust cli in @crates/ and undertsand if there're new things to add and fix.