Server setup instructions for agents

Goal

Help the user install, configure, validate, and start OpenViking with the smallest viable path.

This page is for OpenViking server setup. For client-only CLI setup, use the OpenViking CLI Setup guide instead.

General Principles

Default to the normal end-user installation path; do not default to source builds
Default to prebuilt packages; do not assume Rust / C++ / CMake are required
Read existing configuration and supplied requirements first; ask the user about missing or uncertain values. Do not guess provider, model, api_base, api_key, or workspace
Preserve existing configuration and unrelated fields; inspect the actual changes before updating it
Only move to the source-build path when installation clearly falls back to local compilation, or when the user explicitly asks for a source install

SOP

1. Choose the path

First determine which category the user belongs to.

A. Standard minimal install

Use this path if any of the following is true:

The user just wants OpenViking installed and running
The user just wants to try or integrate OpenViking
The user is not asking for source-level development
The user is not asking to modify low-level native components

Execution path:

Install the Python package
Ask for model configuration
Generate ~/.openviking/ov.conf
Run openviking-server doctor
Start openviking-server

B. Local-model install (Ollama)

Use this path if any of the following is true:

The user explicitly wants local models
The user explicitly wants Ollama
The user does not want to fill in many model settings manually

Execution path:

Install the OpenViking Python package and make sure Ollama is running
Run openviking-server init and select local models
Run openviking-server doctor
Start openviking-server

C. Docker install

Use this path if any of the following is true:

The user explicitly wants to install or run with Docker
The user does not want to install the Python package directly on the host
The user wants configuration and data persisted via a mounted volume

Execution path:

Confirm whether the user already has an ov.conf
If not, confirm model configuration first or guide them to run openviking-server init inside the container
Start the container with the image or docker-compose.yml
Verify /health

D. Windows install

Use this path if any of the following is true:

The user is on Windows
The user asks for Windows installation steps

Execution path:

Prefer the prebuilt-wheel path from the standard minimal install flow
Configure OPENVIKING_CONFIG_FILE with Windows shell syntax
Run openviking-server doctor
Start openviking-server
Only enter the Windows local-build path if wheels are unavailable or installation fails

E. Source build

Only use this path if one of the following is true:

The user explicitly asks for a source install
Installation fails and the error clearly indicates local compilation is required
The current platform has no prebuilt wheel
The user explicitly wants to modify or rebuild low-level native components

Only then explain the required toolchain:

Rust 1.91.1+
A C++ compiler
CMake

2. Ask questions

Check configuration files, environment variables, and choices already supplied. Use the following as an information checklist and ask only about missing values that affect installation. Have the user configure API keys locally or through an existing credential mechanism, rather than paste them into chat.

Required information

Which model provider do you want to use?
- openai
- azure
- volcengine
- openai-codex
- ollama
Have you already decided on:
- the embedding model name
- the VLM model name
- the API key / auth method
Which directory should storage.workspace use?

Follow-up questions by provider

openai

embedding model name
VLM model name
whether to use https://api.openai.com/v1
whether the API key is ready

azure

embedding deployment name
VLM deployment name
Azure API Base
Azure API Key
whether to use the default api_version = 2025-01-01-preview

volcengine

embedding model name
VLM model name
whether to use https://ark.cn-beijing.volces.com/api/v3
whether the API key is ready

openai-codex

whether the user wants to complete Codex OAuth via openviking-server init
VLM model name
which provider and model to use for embedding

ollama

whether the user is okay with running openviking-server init directly
whether Ollama is already installed
which local embedding / VLM models they want to use

Docker information

If the user chooses Docker, also confirm:

whether they want docker run or docker compose
whether the host already has ~/.openviking/ov.conf
whether they want to mount host ~/.openviking to container /app/.openviking
whether they want to inject the full JSON config through OPENVIKING_CONF_CONTENT

Windows information

If the user is on Windows, also confirm:

whether they use PowerShell or cmd.exe
whether they only want a prebuilt-wheel install
if a local build becomes necessary, whether CMake and MinGW are already installed

3. Generate the config

Only write or update ~/.openviking/ov.conf after the user has confirmed all required values, and keep a copy of existing configuration. The placeholder values below are not a working configuration.

Minimal config shape

json

{
  "storage": {
    "workspace": "..."
  },
  "embedding": {
    "dense": {
      "provider": "...",
      "api_base": "...",
      "api_key": "...",
      "model": "..."
    }
  },
  "vlm": {
    "provider": "...",
    "api_base": "...",
    "api_key": "...",
    "model": "..."
  }
}

Optional fields

Only add these when the provider requires them, when the README examples explicitly include them, or when the user explicitly asks for them:

dimension
api_version
max_concurrent
temperature
max_retries

Do not do these things

Do not fill in fake API keys
Do not fill in unconfirmed paths
Do not copy README comments into the JSON file
Do not guess model names or private API endpoints

4. Run commands

Path A: Standard minimal install

Use a Python 3.10+ virtual environment, or follow the Quick Start with uv tool install. In an activated virtual environment:

bash

python -m pip install --upgrade openviking

After the user confirms the configuration, write ~/.openviking/ov.conf, then run:

bash

openviking-server doctor
openviking-server

Path B: Local-model install (Ollama)

Complete the package installation from Path A and start Ollama, then run:

bash

openviking-server init
openviking-server doctor
openviking-server

Path C: Docker install

Option 1: Run the published image directly

If the user already has a local config directory, prefer:

bash

docker run --rm \
  --name openviking \
  -p 127.0.0.1:1933:1933 \
  -v ~/.openviking:/app/.openviking \
  ghcr.io/volcengine/openviking:latest

Notes:

Prefer the ghcr.io image; if pulling fails, use openviking-cn-beijing.cr.volces.com/volcengine/openviking:latest instead
The default config path inside the container is /app/.openviking/ov.conf
Inside the container, HOME=/app
Prefer mounting host ~/.openviking to container /app/.openviking so config, CLI config, and workspace data persist
Web Studio is served by the OV server itself at http://127.0.0.1:1933/studio — no extra port needed

Option 2: Use `docker-compose.yml`

If the user prefers compose, the repo already includes an example with:

image: ghcr.io/volcengine/openviking:latest (if pulling fails, use openviking-cn-beijing.cr.volces.com/volcengine/openviking:latest)
ports: 1933:1933
volume: ~/.openviking:/app/.openviking

In that case, have the user run this from the repo root:

bash

docker compose up -d

Option 3: Initialize config inside the container

If the user does not yet have ov.conf, there are two options:

Generate it on the host first and mount it into the container
Initialize the same mounted directory with a one-off container, then start the service using Option 1:

bash

docker run --rm -it \
  -v ~/.openviking:/app/.openviking \
  ghcr.io/volcengine/openviking:latest openviking-server init

The Dockerfile also supports injecting the full JSON config via OPENVIKING_CONF_CONTENT on first start. Only use that if the user explicitly wants it and all config values have already been confirmed.

Docker validation

/health only confirms a responsive process; a container without configuration returns 503 pending_initialization, so receiving a curl response alone does not establish health. Check logs and /ready:

bash

curl http://localhost:1933/health
curl http://localhost:1933/ready

Path D: Windows install

Prefer the prebuilt-wheel path first:

bat

python -m pip install --upgrade openviking

After the config file is ready, set environment variables using the user’s shell.

PowerShell

powershell

$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf"

cmd.exe

bat

set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf"

Then run:

bat

openviking-server doctor
openviking-server

If the user also wants CLI config:

PowerShell

powershell

$env:OPENVIKING_CLI_CONFIG_FILE = "$HOME/.openviking/ovcli.conf"

cmd.exe

bat

set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf"

Path E: Source build

Prepare Rust, C++, and CMake only when a source build is needed. See CONTRIBUTING.md in the repository for the full build steps.

5. Triage

Case 1: Config file is missing, the path is wrong, or JSON cannot be parsed

Check first:

whether ~/.openviking/ov.conf exists
whether an environment variable or --config points to the wrong path
whether the config file is valid JSON

Handling rule:

fix the config path or JSON syntax first
then rerun openviking-server doctor

Case 2: Model configuration is incomplete

Typical signs:

missing embedding or VLM config
missing provider / model / api_key
openai-codex is configured only for VLM, while embedding is still missing

Handling rule:

fill in the minimal required config first
do not guess model names or keys
if the provider is openai-codex, remind the user that it mainly covers the VLM side and embedding still needs separate confirmation

Case 3: Model service is unreachable or auth is not usable

Check first:

whether API Base is correct
whether the API key / auth method is correct
if using openai-codex, whether OAuth has been completed via openviking-server init
if using Ollama, whether the service is actually running

Handling rule:

fix provider config and auth state first
for Ollama, prefer recommending:

bash

openviking-server init

then rerun:

bash

openviking-server doctor

Case 4: Local dependency or packaged artifact is unavailable

Typical signs:

the native engine module cannot be imported
AGFS / RAGFS-related bindings are unavailable
packaged artifacts are missing after installation

Handling rule:

first try a standard reinstall:

bash

python -m pip install --upgrade --force-reinstall openviking

if it still fails, then decide whether to move to the source-build path
do not immediately require the full local build toolchain

Case 5: Installation falls into local compilation

Confirm first whether this is because:

the current platform has no compatible wheel
the user is already doing a source install
prebuilt artifacts are unavailable

Handling rule:

only after confirming the source-build path should you add Rust / C++ / CMake
on Windows, local compilation usually means CMake and MinGW become relevant first
do not present source-build dependencies as the default install prerequisites

Case 6: Windows installation fails

Check in this order:

whether the current Python version / architecture matches a prebuilt wheel
whether installation actually fell into source compilation
whether environment variables were set correctly for PowerShell or cmd.exe
if local compilation is happening, whether CMake / MinGW are missing

Handling rule:

fix wheel, path, and environment variable issues first
only add build dependencies if local compilation is clearly required

Case 7: Docker starts but OpenViking is unusable

Check first:

whether ~/.openviking is correctly mounted to /app/.openviking
whether /app/.openviking/ov.conf exists inside the container
whether model configuration is complete
whether curl http://localhost:1933/health succeeds
whether the container still needs openviking-server init

Handling rule:

fix volume mounts and config first
then validate provider, model, and auth settings

Case 8: The user does not know which models to choose

Do not write the config yet.

Guidance rules:

if the user already has an account with a specific cloud provider, prefer that provider first
if the user wants local execution, prefer Ollama + openviking-server init
if the user wants openai-codex, remind them that it mainly solves the VLM side and embedding still needs to be configured separately

Additional reference

OpenViking GitHub repository

Server setup instructions for agents ​

Goal ​

General Principles ​

SOP ​

1. Choose the path ​

A. Standard minimal install ​

B. Local-model install (Ollama) ​

C. Docker install ​

D. Windows install ​

E. Source build ​

2. Ask questions ​

Required information ​

Follow-up questions by provider ​

openai ​

azure ​

volcengine ​

openai-codex ​

ollama ​

Docker information ​

Windows information ​

3. Generate the config ​

Minimal config shape ​

Optional fields ​

Do not do these things ​

4. Run commands ​

Path A: Standard minimal install ​

Path B: Local-model install (Ollama) ​

Path C: Docker install ​

Option 1: Run the published image directly ​

Option 2: Use docker-compose.yml ​

Option 3: Initialize config inside the container ​

Docker validation ​

Path D: Windows install ​

PowerShell ​

cmd.exe ​

PowerShell ​

cmd.exe ​

Path E: Source build ​

5. Triage ​

Case 1: Config file is missing, the path is wrong, or JSON cannot be parsed ​

Case 2: Model configuration is incomplete ​

Case 3: Model service is unreachable or auth is not usable ​

Case 4: Local dependency or packaged artifact is unavailable ​

Case 5: Installation falls into local compilation ​

Case 6: Windows installation fails ​

Case 7: Docker starts but OpenViking is unusable ​

Case 8: The user does not know which models to choose ​

Additional reference ​

Server setup instructions for agents

Goal

General Principles

SOP

1. Choose the path

A. Standard minimal install

B. Local-model install (Ollama)

C. Docker install

D. Windows install

E. Source build

2. Ask questions

Required information

Follow-up questions by provider

openai

azure

volcengine

openai-codex

ollama

Docker information

Windows information

3. Generate the config

Minimal config shape

Optional fields

Do not do these things

4. Run commands

Path A: Standard minimal install

Path B: Local-model install (Ollama)

Path C: Docker install

Option 1: Run the published image directly

Option 2: Use `docker-compose.yml`

Option 3: Initialize config inside the container

Docker validation

Path D: Windows install

PowerShell

cmd.exe

PowerShell

cmd.exe

Path E: Source build

5. Triage

Case 1: Config file is missing, the path is wrong, or JSON cannot be parsed

Case 2: Model configuration is incomplete

Case 3: Model service is unreachable or auth is not usable

Case 4: Local dependency or packaged artifact is unavailable

Case 5: Installation falls into local compilation

Case 6: Windows installation fails

Case 7: Docker starts but OpenViking is unusable

Case 8: The user does not know which models to choose

Additional reference