Configuration

Complete configuration guide for OpenViking including models, storage, and server settings

OpenViking uses JSON configuration files to manage settings for embedding models, storage backends, server deployment, and more.

Configuration Files

OpenViking uses two config files:

File	Purpose	Default Path
ov.conf	SDK embedded mode + server config	~/.openviking/ov.conf
ovcli.conf	HTTP client and CLI connection to remote server	~/.openviking/ovcli.conf

When config files are at the default path, OpenViking loads them automatically — no additional setup needed.

If config files are at a different location:

Environment Variable

export OPENVIKING_CONFIG_FILE=/path/to/ov.conf
export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf

Quick Start Configuration

Create ~/.openviking/ov.conf:

{
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "api_key": "your-api-key",
      "model": "doubao-embedding-vision-250615",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "vlm": {
    "provider": "volcengine",
    "api_key": "your-api-key",
    "model": "doubao-seed-2-0-pro-260215"
  },
  "storage": {
    "workspace": "./data",
    "agfs": { "backend": "local" },
    "vectordb": { "backend": "local" }
  }
}

Embedding Configuration

Embedding models convert text and multimodal content into vectors for semantic search.

Dense Embedding

{
  "embedding": {
    "max_concurrent": 10,
    "dense": {
      "provider": "volcengine",
      "api_key": "your-api-key",
      "model": "doubao-embedding-vision-250615",
      "dimension": 1024,
      "input": "multimodal"
    }
  }
}

Parameters

Parameter	Type	Description
max_concurrent	int	Maximum concurrent embedding requests (default: 10)
provider	string	"volcengine", "openai", "vikingdb", or "jina"
api_key	string	API key for authentication
model	string	Model name
dimension	int	Vector dimension (must match model output)
input	string	Input type: "text" or "multimodal"
batch_size	int	Batch size for embedding requests

Volcengine (Doubao) Configuration

{
  "embedding": {
    "dense": {
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "your-volcengine-api-key",
      "provider": "volcengine",
      "dimension": 1024,
      "model": "doubao-embedding-vision-250615",
      "input": "multimodal"
    }
  }
}

Recommended models:

• doubao-embedding-vision-250615 (1024 dim, multimodal)
• doubao-embedding-250615 (1024 dim, text only)

OpenAI Configuration

{
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "your-openai-api-key",
      "provider": "openai",
      "dimension": 3072,
      "model": "text-embedding-3-large"
    }
  }
}

Jina AI Configuration

{
  "embedding": {
    "dense": {
      "provider": "jina",
      "api_key": "jina_xxx",
      "model": "jina-embeddings-v5-text-small",
      "dimension": 1024
    }
  }
}

Available models:

• jina-embeddings-v5-text-small: 677M params, 1024 dim, max seq 32768
• jina-embeddings-v5-text-nano: 239M params, 768 dim, max seq 8192

Get your API key at jina.ai. Jina models support local deployment via GGUF/MLX.

Hybrid Embedding

Combine dense and sparse embeddings for better retrieval:

Single Hybrid Model

{
  "embedding": {
    "hybrid": {
      "provider": "volcengine",
      "api_key": "your-api-key",
      "model": "doubao-embedding-hybrid",
      "dimension": 1024
    }
  }
}

VLM Configuration

Vision Language Models generate semantic abstracts (L0) and overviews (L1) for resources.

{
  "vlm": {
    "api_key": "your-api-key",
    "model": "doubao-seed-2-0-pro-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "thinking": false,
    "max_concurrent": 100
  }
}

Parameters

Parameter	Type	Description
api_key	string	API key
model	string	Model name
api_base	string	API endpoint (optional)
thinking	boolean	Enable thinking mode for VolcEngine models (default: false)
max_concurrent	int	Maximum concurrent semantic LLM calls (default: 100)

If VLM is not configured, L0/L1 will be generated from content directly (less semantic), and multimodal resources may have limited descriptions.

Storage Configuration

Configure file storage (AGFS) and vector database backends.

{
  "storage": {
    "workspace": "./data",
    "agfs": {
      "backend": "local",
      "timeout": 10
    },
    "vectordb": {
      "backend": "local",
      "name": "context",
      "project": "default"
    }
  }
}

AGFS Backend

Parameter	Type	Description	Default
mode	string	"http-client" or "binding-client"	"http-client"
backend	string	"local", "s3", or "memory"	"local"
url	string	AGFS service URL for http-client mode	"http://localhost:1833"
timeout	float	Request timeout in seconds	10.0

S3 Backend Configuration

{
  "storage": {
    "agfs": {
      "backend": "s3",
      "s3": {
        "bucket": "my-bucket",
        "endpoint": "s3.amazonaws.com",
        "region": "us-east-1",
        "access_key": "your-ak",
        "secret_key": "your-sk",
        "use_ssl": true,
        "use_path_style": true
      }
    }
  }
}

S3 Parameters

Parameter	Description
bucket	S3 bucket name
region	AWS region (e.g., us-east-1, cn-beijing)
access_key	S3 access key ID
secret_key	S3 secret access key
endpoint	Custom S3 endpoint for MinIO, LocalStack, etc.
prefix	Optional key prefix for namespace isolation
use_ssl	Enable HTTPS (default: true)
use_path_style	Use PathStyle (MinIO, SeaweedFS) vs VirtualHostStyle (TOS)

Vector Database Backend

Parameter	Type	Description	Default
backend	string	"local", "http", "volcengine", or "vikingdb"	"local"
name	string	VectorDB collection name	"context"
url	string	Remote service URL for http backend	null
project_name	string	Project name	"default"
dimension	int	Vector embedding dimension	0

Volcengine VikingDB

{
  "storage": {
    "vectordb": {
      "name": "context",
      "backend": "volcengine",
      "project": "default",
      "volcengine": {
        "region": "cn-beijing",
        "ak": "your-access-key",
        "sk": "your-secret-key"
      }
    }
  }
}

Server Configuration

When running OpenViking as an HTTP service, add a server section:

{
  "server": {
    "host": "0.0.0.0",
    "port": 1933,
    "root_api_key": "your-secret-root-key",
    "cors_origins": ["*"]
  }
}

Field	Type	Description	Default
host	string	Bind address	"0.0.0.0"
port	int	Bind port	1933
root_api_key	string	Root API key for multi-tenant auth (disabled if not set)	null
cors_origins	array	Allowed CORS origins	["*"]

When root_api_key is not set, authentication is disabled (dev mode). This is only allowed when binding to localhost (127.0.0.1).

CLI Client Configuration

Create ~/.openviking/ovcli.conf for the HTTP client and CLI:

{
  "url": "http://localhost:1933",
  "api_key": "your-secret-key",
  "agent_id": "my-agent",
  "timeout": 60.0,
  "output": "table",
  "echo_command": true
}

Field	Description	Default
url	Server address	(required)
api_key	API key for authentication	null
agent_id	Agent identifier for isolation	null
timeout	Request timeout in seconds	60.0
output	Output format: "table" or "json"	"table"

Advanced Configuration

Code Summary Mode

Control how code files are summarized:

{
  "code": {
    "code_summary_mode": "ast"
  }
}

Mode	Description
"ast"	Extract AST skeleton (class names, method signatures) for files ≥100 lines (recommended)
"llm"	Always use LLM for summarization (higher cost)
"ast_llm"	Extract AST first, then pass to LLM (highest quality)

Reranking

Reranking improves search result quality:

{
  "rerank": {
    "provider": "volcengine",
    "api_key": "your-api-key",
    "model": "doubao-rerank-250615",
    "threshold": 0.1
  }
}

Logging

{
  "log": {
    "level": "INFO",
    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    "output": "stdout",
    "rotation": true,
    "rotation_days": 3
  }
}

Troubleshooting

API Key Error

Error: Invalid API key

Check your API key is correct and has the required permissions.

Vector Dimension Mismatch

Error: Vector dimension mismatch

Ensure the dimension in config matches the model’s output dimension.

VLM Timeout

Error: VLM request timeout

• Check network connectivity
• Increase timeout in config
• Try a smaller model

Related Resources

Deployment

Server deployment and production setup

Authentication

API key setup and multi-tenant auth

Python SDK

Complete Python SDK reference

CLI Usage

Command-line interface guide