Server Configuration

For initial setup, run openviking-server init, then run openviking-server doctor after saving the configuration.

The OpenViking server reads ov.conf. The default path is:

~/.openviking/ov.conf

Use an environment variable or startup option to select another file:

export OPENVIKING_CONFIG_FILE=/path/to/ov.conf
openviking-server --config /path/to/ov.conf

The server reads the file at startup. Restart the server after changing models, retrieval, storage, or server settings, then run openviking-server doctor.

Configuration Structure

{
  "embedding": {},
  "vlm": {},
  "query_planner": {},
  "rerank": {},
  "retrieval": {},
  "storage": {},
  "server": {},
  "memory": {},
  "parsers": {},
  "encryption": {},
  "log": {},
  "telemetry": {}
}

Optional sections use their defaults when omitted. Unknown fields are rejected.

Top-Level Settings

auto_generate_l0, auto_generate_l1, default_search_mode, and default_search_limit are deprecated compatibility fields. They are accepted when loading older configuration files but have no runtime effect.

Model Settings

API-based embedding, vlm, query_planner, and rerank configurations reuse some field names, but each module has its own schema. Use only fields supported by the applicable module below.

{
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "model": "doubao-embedding-vision-251215",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "<your-ark-api-key>",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "vlm": {
    "provider": "volcengine",
    "model": "doubao-seed-2-0-code-preview-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "<your-ark-api-key>",
    "temperature": 0,
    "max_retries": 3,
    "thinking": false
  },
  "query_planner": {
    "provider": "volcengine",
    "model": "doubao-seed-2-0-code-preview-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "<your-ark-api-key>",
    "thinking": false
  },
  "rerank": {
    "provider": "vikingdb",
    "ak": "<your-volcengine-ak>",
    "sk": "<your-volcengine-sk>",
    "host": "api-vikingdb.vikingdb.cn-beijing.volces.com",
    "model_name": "doubao-seed-rerank",
    "model_version": "251028",
    "threshold": 0.1,
    "max_input_tokens": 0
  }
}

embedding.dense

Changing the model or dimension can make existing vector collections incompatible and may require migration or reindexing.

rerank

Rerank has no separate enabled field. It becomes available when the required provider credentials are configured.

Setting provider explicitly requires the credentials that provider needs: ak and sk for vikingdb, api_key for cohere, api_key and api_base for openai, model for litellm. An incomplete block is rejected when the configuration loads.

Retrieval Settings

{
  "retrieval": {
    "hotness_alpha": 0,
    "score_propagation_alpha": 1,
    "enable_intent": true
  }
}

retrieval

Search and Find requests default to limit: 10; override the limit on each API or SDK request. retrieval.enable_intent controls LLM query planning for session-aware Search, while result reranking is enabled only when rerank has a usable provider configuration.

Storage Settings

{
  "storage": {
    "workspace": "./data",
    "skip_process_lock": false,
    "agfs": {
      "backend": "local"
    },
    "vectordb": {
      "backend": "local"
    }
  }
}

storage

Remote backends also require endpoint, bucket/collection, credentials, and timeout fields. See Configuration for complete examples.

Queue Worker Settings

queue_workers.external_parse

This setting controls queue-job concurrency. It is separate from vlm.media.max_concurrent, which limits audio/video VLM calls, and does not limit individual Understanding API HTTP requests.

queue_workers.add_resource

max_concurrent controls independent AddResource jobs, while file_vectorization_concurrency controls files within one vectors-only directory job. It does not affect single-file resources or semantic_and_vectors processing.

queue_workers.session_commit

Reindex Settings

reindex

HTTP Server Settings

{
  "server": {
    "host": "127.0.0.1",
    "port": 1933,
    "workers": 1,
    "auth_mode": "dev",
    "cors_origins": ["http://localhost:5173"],
    "profile_enabled": false,
    "temp_upload": {
      "default_mode": "local"
    }
  }
}

server

Encryption and API Key Hashing

File encryption and API key hashing are configured in the top-level encryption section, not under server:

{
  "encryption": {
    "enabled": false,
    "api_key_hashing": {
      "enabled": false
    }
  }
}

See Encryption for provider and key-management settings.

Authentication Modes

Memory Settings

{
  "memory": {
    "custom_templates_dir": "",
    "experimental_memory_switch": false,
    "eager_prefetch": true,
    "prefetch_search_topn": 5,
    "extraction_enabled": true,
    "session_skill_extraction_enabled": false,
    "link_enabled": false,
    "v2_lock_retry_interval_seconds": 0.2,
    "v2_lock_max_retries": 0
  }
}

memory

Parser Settings

Parsers live under parsers:

{
  "parsers": {
    "pdf": {},
    "code": {
      "code_summary_mode": "ast",
      "extract_functions": true,
      "extract_classes": true,
      "max_token_limit": 50000
    },
    "image": {},
    "audio": {},
    "video": {},
    "markdown": {},
    "anydoc": {
      "enabled": true
    },
    "html": {},
    "text": {},
    "directory": {
      "preserve_structure": true,
      "max_files": 1000,
      "max_depth": 10,
      "max_concurrent": 4
    },
    "feishu": {
      "domain": "https://open.feishu.cn",
      "max_rows_per_sheet": 1000,
      "max_records_per_table": 1000,
      "download_images": true
    },
    "webfeed": {}
  }
}

parsers.directory.max_concurrent is shared by all directory imports in the server event loop. With the default value 4, one directory can run four Understanding jobs concurrently, while multiple concurrent directories still run at most four in total.

max_files and max_depth apply when Understanding directory routing is enabled. Each DirectoryParser scan applies these limits independently before submitting its own Understanding requests. A nested ZIP starts a new directory scan and does not share the outer scan's file-count or depth budget. When Understanding is disabled, native OpenViking directory parsing does not apply these two limits.

When a local directory is added through the client, the complete directory ZIP is subject to the /resources/temp_upload size limit. After extraction, DirectoryParser does not impose a common per-file byte limit. Each selected file follows the limits and upload behavior of its assigned built-in parser or Understanding API backend.

Provider-, parser-, storage-, and encryption-specific fields are documented in Configuration.

Minimal Example

{
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "model": "doubao-embedding-vision-251215",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "<your-ark-api-key>",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "vlm": {
    "provider": "volcengine",
    "model": "doubao-seed-2-0-code-preview-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "<your-ark-api-key>",
    "thinking": false
  },
  "storage": {
    "workspace": "./data"
  },
  "server": {
    "host": "127.0.0.1",
    "port": 1933
  }
}