Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Server configuration for OpenViking HTTP Server."""
import sys
from typing import Any, Dict, List, Literal, Optional
from pydantic import BaseModel, Field, ValidationError, field_validator
# Import auth plugin registry for config validation
from openviking.server.auth.ldap_config import LDAPConfig
from openviking.server.auth.oidc_config import OIDCConfig
from openviking.server.auth.registry import get_registry
from openviking.server.identity import AuthMode
from openviking_cli.utils import get_logger
from openviking_cli.utils.config.agent_evolution_config import AgentEvolutionConfig
from openviking_cli.utils.config.config_loader import (
load_json_config,
resolve_config_path,
)
from openviking_cli.utils.config.config_utils import (
DEFAULT_SERVICE_NAME,
format_validation_error,
normalize_service_name,
warn_unknown_config_fields,
)
from openviking_cli.utils.config.consts import (
DEFAULT_CONFIG_DIR,
DEFAULT_OV_CONF,
OPENVIKING_CONFIG_ENV,
SYSTEM_CONFIG_DIR,
)
from openviking_cli.utils.config.ttl_config import TTLConfig
logger = get_logger(__name__)
def _normalize_config_uri(value: Optional[str], field_name: str) -> Optional[str]:
if value is None:
return None
if not isinstance(value, str):
raise ValueError(f"{field_name} must be a string")
uri = value.strip().rstrip("/")
if not uri:
raise ValueError(f"{field_name} must not be empty")
return uri
def _rewrite_legacy_current_user_uri(uri: str, field_name: str) -> str:
"""Rewrite legacy uid-less current-user spellings to the ``~`` home alias.
``viking://user/resources[/...]`` and ``viking://user/skills`` are no longer
expanded at request boundaries, but stored configurations (ov.conf
``user_config_defaults.add_targets``, persisted ``user_config.json``, old
PATCH bodies) may still carry them. Their intent was unambiguous, so
normalize them here instead of breaking existing deployments.
"""
from openviking.core.namespace import uri_parts
try:
parts = uri_parts(uri.rstrip("/"))
except ValueError:
return uri
if parts[:2] not in (["user", "resources"], ["user", "skills"]):
return uri
rewritten = f"viking://~/{'/'.join(parts[1:])}"
logger.info(
"Rewrote legacy current-user %s %r to %r; use the viking://~ home alias instead.",
field_name,
uri,
rewritten,
)
return rewritten
class AddTargetsConfig(BaseModel):
"""Add targets for resource and skill writes."""
resource_uri: Optional[str] = None
skill_uri: Optional[str] = None
@field_validator("resource_uri")
@classmethod
def validate_resource_uri(cls, value: Optional[str]) -> Optional[str]:
uri = _normalize_config_uri(value, "resource_uri")
if uri is None:
return None
from openviking.core.namespace import classify_uri, uri_parts
from openviking.core.uri_validation import validate_viking_uri
uri = _rewrite_legacy_current_user_uri(uri, "resource_uri")
validate_viking_uri(uri, field_name="resource_uri")
normalized = uri.rstrip("/")
parts = uri_parts(normalized)
classification = classify_uri(normalized)
if (
parts[:1] == ["resources"]
or parts[:2] == ["~", "resources"]
or (
parts[:1] == ["user"]
and classification.context_type == "resource"
and classification.content_index is not None
)
):
return normalized
raise ValueError(
"resource_uri must be a resource directory URI: viking://resources/..., "
"viking://~/resources[/...], or viking://user/{user_id}/resources[/...]"
)
@field_validator("skill_uri")
@classmethod
def validate_skill_uri(cls, value: Optional[str]) -> Optional[str]:
uri = _normalize_config_uri(value, "skill_uri")
if uri is None:
return None
from openviking.core.namespace import uri_parts
from openviking.core.uri_validation import validate_viking_uri
uri = _rewrite_legacy_current_user_uri(uri, "skill_uri")
validate_viking_uri(uri, field_name="skill_uri")
normalized = uri.rstrip("/")
parts = uri_parts(normalized)
if parts in (["~", "skills"], ["agent", "skills"]) or (
len(parts) == 3 and parts[0] == "user" and parts[2] == "skills"
):
return normalized
raise ValueError(
"skill_uri must be viking://~/skills, viking://user/{user_id}/skills, "
"or viking://agent/skills"
)
class DeprecatedUserAgentEvolutionConfig(BaseModel):
"""Parse-only compatibility for legacy per-user configuration files."""
enabled: Optional[bool] = None
class UserConfig(BaseModel):
"""User configuration values that can be defaulted or initialized."""
add_targets: AddTargetsConfig = Field(default_factory=AddTargetsConfig)
memory_policy: Optional[Dict[str, Any]] = None
ttl: Optional[TTLConfig] = None
agent_evolution: DeprecatedUserAgentEvolutionConfig = Field(
default_factory=DeprecatedUserAgentEvolutionConfig,
exclude=True,
)
@field_validator("memory_policy", mode="before")
@classmethod
def validate_memory_policy(cls, value: Any) -> Optional[Dict[str, Any]]:
if value is None:
return None
from openviking.session.memory_policy import MemoryPolicy
return MemoryPolicy.from_dict(value).to_dict()
class UserConfigDefaults(UserConfig):
"""Deployment defaults for users without persisted overrides."""
auto_commit_policy: Optional[Dict[str, Any]] = None
@field_validator("auto_commit_policy", mode="before")
@classmethod
def validate_auto_commit_policy(cls, value: Any) -> Optional[Dict[str, Any]]:
from openviking.session.auto_commit_policy import (
AutoCommitPolicy,
validate_idle_timeout_input,
)
if value is None:
return None
if isinstance(value, dict) and "idle_timeout_seconds" in value:
validate_idle_timeout_input(value["idle_timeout_seconds"])
return AutoCommitPolicy.from_dict(value).to_dict()
class MetricsAccountDimensionConfig(BaseModel):
"""Account-dimension configuration for metrics label injection."""
# Enabled by default, but still allowlist-gated to avoid accidental high-cardinality exposure.
enabled: bool = True
max_active_accounts: int = 100
metric_allowlist: List[str] = Field(default_factory=list)
class PrometheusExporterConfig(BaseModel):
"""Prometheus exporter configuration."""
enabled: bool = True
class OTelExporterConfig(BaseModel):
"""OpenTelemetry exporter configuration."""
class TLSConfig(BaseModel):
"""TLS configuration for OTLP exporters."""
insecure: bool = False
enabled: bool = False
protocol: str = "grpc" # "grpc", "http", or "local" for traces
tls: TLSConfig = Field(default_factory=TLSConfig)
endpoint: str = "localhost:4317" # gRPC default: 4317; HTTP default: 4318
service_name: str = "openviking-server"
export_interval_ms: int = 10000
headers: Dict[str, str] = Field(default_factory=dict)
local_path: str = "~/.openviking/logs/traces.jsonl"
local_rotation_mb: int = Field(default=40, gt=0)
local_backup_count: int = Field(default=2, ge=0)
class MetricsExportersConfig(BaseModel):
"""Metrics exporters configuration."""
prometheus: PrometheusExporterConfig = Field(default_factory=PrometheusExporterConfig)
otel: OTelExporterConfig = Field(default_factory=OTelExporterConfig)
class MetricsConfig(BaseModel):
"""Metrics subsystem configuration."""
enabled: bool = False
bot_data_path: Optional[str] = None
account_dimension: MetricsAccountDimensionConfig = Field(
default_factory=MetricsAccountDimensionConfig
)
exporters: MetricsExportersConfig = Field(default_factory=MetricsExportersConfig)
class UsageAuditConfig(BaseModel):
"""Product usage and audit projection configuration."""
enabled: bool = True
backend: Literal["sqlite"] = "sqlite"
sqlite_path: Optional[str] = None
queue_size: int = Field(10_000, gt=0)
batch_size: int = Field(500, gt=0)
flush_interval_seconds: float = Field(1.0, gt=0)
shutdown_flush_timeout_seconds: float = Field(3.0, gt=0)
usage_retention_days: int = Field(14, ge=0)
audit_retention_days: int = Field(7, ge=0)
audit_retention_per_account: int = Field(1000, ge=0)
timezone: str = "local"
inventory_ttl_seconds: float = Field(10.0, ge=0)
class UsageReporterSinkConfig(BaseModel):
"""Usage reporter sink configuration."""
type: Literal["custom", "file_log"] = "custom"
class_path: Optional[str] = None
config: Dict[str, object] = Field(default_factory=dict)
class UsageReporterConfig(BaseModel):
"""Usage event reporter configuration."""
enabled: bool = False
extractors: List[Literal["memory_usage"]] = Field(default_factory=lambda: ["memory_usage"])
sinks: List[UsageReporterSinkConfig] = Field(default_factory=list)
class TTLAdapterConfig(BaseModel):
"""Opt-in Redis-backed directory TTL configuration.
Uses the built-in implementation, supplied with its ResourceID, Redis
connection and writer/reader role through ``config``. No external Python
package is required. Unset or disabled leaves all TTL hooks inactive.
"""
enabled: bool = False
config: Dict[str, object] = Field(default_factory=dict)
@property
def writer_enabled(self) -> bool:
return self.enabled and bool(self.config.get("writer", True))
class TraceDumpBodyConfig(BaseModel):
"""HTTP body dump configuration.
Attaches request/response bodies as attributes on the active trace span so
they can be inspected in trace UIs. Off by default — bodies may contain
secrets and high-cardinality content.
"""
enabled: bool = False
max_bytes: int = 4096
class ObservabilityConfig(BaseModel):
"""Server-side observability configuration."""
metrics: MetricsConfig = Field(default_factory=MetricsConfig)
usage_audit: UsageAuditConfig = Field(default_factory=UsageAuditConfig)
traces: OTelExporterConfig = Field(default_factory=OTelExporterConfig)
logs: OTelExporterConfig = Field(default_factory=OTelExporterConfig)
dump_body: TraceDumpBodyConfig = Field(default_factory=TraceDumpBodyConfig)
class TempUploadConfig(BaseModel):
"""Temporary upload configuration."""
default_mode: Literal["local", "shared"] = "local"
shared_max_size_bytes: int = 512 * 1024 * 1024
ttl_seconds: int = Field(12 * 60 * 60, ge=0)
# When True, shared-upload cleanup also removes directories whose names are
# not valid upload ids (missing/garbled `<ms-ts>-<uuid>` format). Off by
# default so a malformed entry never triggers an unexpected delete; enable
# to reclaim junk directories that would otherwise be skipped forever.
cleanup_invalid_dirs: bool = False
class ToolOutputExternalizationConfig(BaseModel):
"""External storage controls for oversized tool outputs."""
enabled: bool = True
threshold_chars: int = 20_000
preview_chars: int = 2_000
assistant_turn_inline_budget_chars: int = 100_000
assistant_turn_preview_budget_chars: int = 10_000
min_preview_chars: int = 1_000
aggregate_selection_strategy: Literal["largest_first"] = "largest_first"
failure_mode: Literal["reject", "preserve_raw", "preview_only"] = "preserve_raw"
class AccountStoreConfig(BaseModel):
"""Startup-only selection of the complete account store provider."""
provider: str = "file"
params: Dict[str, Any] = Field(default_factory=dict)
@field_validator("provider")
@classmethod
def _validate_provider(cls, value: str) -> str:
normalized = value.strip().lower()
supported = {"file", "mysql", "redis_mysql"}
if normalized not in supported:
raise ValueError(
"account_store.provider must be one of: " + ", ".join(sorted(supported))
)
return normalized
class ServerConfig(BaseModel):
host: str = "127.0.0.1"
port: int = 1933
workers: int = 1
executor_threads: int = Field(
default=0,
ge=0,
description=(
"Maximum number of threads in each server process's default asyncio "
"executor. Zero keeps Python's default sizing policy."
),
)
# Seconds an idle HTTP keep-alive connection is kept open before the server
# closes it. Defaults to 5 to match uvicorn's built-in default and preserve
# the existing service behavior. Raise it above the idle-connection lifetime
# of any upstream client or load balancer that reuses connections (e.g. the
# serverless VKE forwarder keeps idle connections for up to 60s via
# WithMaxIdleConnDuration(1*time.Minute)); otherwise the server may close
# connections the client still believes are reusable, causing sporadic
# connection-reset / EOF errors.
timeout_keep_alive: int = 5
auth_mode: Optional[str] = None # If None, auto-detect based on root_api_key
root_api_key: Optional[str] = None
# OIDC/LDAP authentication configuration
oidc: Optional[OIDCConfig] = None
ldap: Optional[LDAPConfig] = None
profile_enabled: bool = False
cors_origins: List[str] = Field(default_factory=lambda: ["*"])
with_bot: bool = False # Enable Bot API proxy to Vikingbot
bot_api_url: str = "http://localhost:18790" # Vikingbot OpenAPIChannel URL (default port)
encryption_enabled: bool = False # Whether file-level AES encryption is enabled
api_key_hashing_enabled: bool = False # Whether API key Argon2id hashing is enabled (default: false, rely on file encryption)
# When true, poll the shared key store and reload the in-memory index on change so
# read replicas pick up writer-side user add/rotate/remove. Default off (single writer).
api_key_watch_enabled: bool = False
# Poll interval; each check only stats registry files and reads fully on change.
api_key_watch_interval_seconds: float = 30.0
account_store: AccountStoreConfig = Field(default_factory=AccountStoreConfig)
# Trusted-mode identity registration is batched in memory; 0 disables it.
trusted_identity_flush_interval_seconds: float = Field(300.0, ge=0)
trusted_identity_pending_max_size: int = Field(10_000, gt=0)
observability: ObservabilityConfig = Field(default_factory=ObservabilityConfig)
usage_reporter: UsageReporterConfig = Field(default_factory=UsageReporterConfig)
# Built-in Redis TTL; disabled unless explicitly configured.
ttl_adapter: Optional[TTLAdapterConfig] = None
# Public-facing base URL emitted in MCP-issued upload instructions. See
# ``openviking.server.mcp_endpoint._resolve_public_base_url`` for the full
# resolution chain: env var > this field > X-Forwarded-Host/Proto > Host header
# > listen-address fallback. Set this (or the env var) when the server runs
# behind a reverse proxy that does not forward X-Forwarded-* headers.
public_base_url: Optional[str] = None
upload_signed_ttl_seconds: int = 600
temp_upload: TempUploadConfig = Field(default_factory=TempUploadConfig)
user_config_defaults: UserConfigDefaults = Field(default_factory=UserConfigDefaults)
agent_evolution: AgentEvolutionConfig = Field(default_factory=AgentEvolutionConfig)
tool_output_externalization: ToolOutputExternalizationConfig = Field(
default_factory=ToolOutputExternalizationConfig
)
@field_validator("user_config_defaults", mode="before")
@classmethod
def normalize_user_config_defaults(cls, value: Any) -> Any:
return value.model_dump() if isinstance(value, UserConfig) else value
def get_effective_auth_mode(self) -> str:
"""Get effective auth mode, auto-detecting if not explicitly set.
- If root_api_key is configured (non-empty) and auth_mode is None: api_key
- If root_api_key is not configured and auth_mode is None: dev
"""
auth_mode_text = str(self.auth_mode).strip() if self.auth_mode is not None else ""
if auth_mode_text:
return auth_mode_text
if self.root_api_key is not None and str(self.root_api_key).strip():
return AuthMode.API_KEY.value
return AuthMode.DEV.value
def map_bind_host_to_loopback(host: str) -> str:
"""Map a server *bind* host to a client-connectable *loopback* host.
``server.host`` configures the address the server binds/listens on. A
wildcard bind address such as ``0.0.0.0`` (or IPv6 ``::``) is valid to
listen on but is *not* a destination a client can connect to. Clients that
derive a connect URL from the configured host (the bot proxy, the bot's
own config loader, ``doctor``) must translate the wildcard to loopback:
- ``"0.0.0.0"``, ``""``, ``"*"`` -> ``"127.0.0.1"``
- ``"::"``, ``"::0"``, ``"[::]"`` -> ``"[::1]"``
- bare IPv6 literals (e.g. ``"::1"``) are bracketed for URL syntax
- everything else passes through unchanged
"""
host = str(host or "").strip()
if host in ("0.0.0.0", "", "*"):
return "127.0.0.1"
if host in ("::", "::0", "[::]"):
return "[::1]"
if ":" in host and not (host.startswith("[") and host.endswith("]")):
return f"[{host}]"
return host
def get_server_url_from_server_data(server_data: object) -> str:
"""Return the loopback URL clients use for the configured OpenViking server."""
if isinstance(server_data, dict):
host_value = server_data.get("host")
port_value = server_data.get("port")
else:
host_value = getattr(server_data, "host", None)
port_value = getattr(server_data, "port", None)
host = map_bind_host_to_loopback(str(host_value or "127.0.0.1"))
port = str(port_value or "1933").strip()
return f"http://{host}:{port}"
def _inherit_otel_service_names(server_data: Dict[str, Any], service_name: str) -> None:
"""Fill omitted OTel service_name fields from the top-level service name."""
if "observability" not in server_data:
server_data["observability"] = {}
observability = server_data["observability"]
if not isinstance(observability, dict):
return
for key in ("traces", "logs"):
if key not in observability:
observability[key] = {"service_name": service_name}
elif isinstance(observability[key], dict) and "service_name" not in observability[key]:
observability[key]["service_name"] = service_name
if "metrics" not in observability:
observability["metrics"] = {}
metrics = observability["metrics"]
if not isinstance(metrics, dict):
return
if "exporters" not in metrics:
metrics["exporters"] = {}
exporters = metrics["exporters"]
if not isinstance(exporters, dict):
return
if "otel" not in exporters:
exporters["otel"] = {"service_name": service_name}
elif isinstance(exporters["otel"], dict) and "service_name" not in exporters["otel"]:
exporters["otel"]["service_name"] = service_name
def load_server_config(config_path: Optional[str] = None) -> ServerConfig:
"""Load server configuration from ov.conf.
Reads the ``server`` section of ov.conf and also ensures the full
ov.conf is loaded into the OpenVikingConfigSingleton so that model
and storage settings are available.
Resolution chain:
1. Explicit ``config_path`` (from --config)
2. OPENVIKING_CONFIG_FILE environment variable
3. ~/.openviking/ov.conf
Args:
config_path: Explicit path to ov.conf.
Returns:
ServerConfig instance with defaults for missing fields.
Raises:
FileNotFoundError: If no config file is found.
"""
path = resolve_config_path(config_path, OPENVIKING_CONFIG_ENV, DEFAULT_OV_CONF)
if path is None:
default_path_user = DEFAULT_CONFIG_DIR / DEFAULT_OV_CONF
default_path_system = SYSTEM_CONFIG_DIR / DEFAULT_OV_CONF
raise FileNotFoundError(
f"OpenViking configuration file not found.\n"
f"Please create {default_path_user} or {default_path_system}, or set {OPENVIKING_CONFIG_ENV}.\n"
f"See: https://openviking.ai/docs"
)
data = load_json_config(path)
server_data = data.get("server", {})
if server_data is None:
server_data = {}
if not isinstance(server_data, dict):
raise ValueError(f"Invalid server config in {path}: 'server' section must be an object")
server_data = dict(server_data)
service_name = normalize_service_name(data.get("service_name", DEFAULT_SERVICE_NAME))
_inherit_otel_service_names(server_data, service_name)
# Convert auth_mode string — built-in enums are converted to their string
# value; custom modes are kept as-is for plugin extensibility.
if "auth_mode" in server_data and isinstance(server_data["auth_mode"], str):
try:
server_data["auth_mode"] = AuthMode(server_data["auth_mode"]).value
except ValueError:
# Custom auth mode — keep as string for plugin registration
pass
# Get encryption enabled from config data directly (for test compatibility)
encryption_enabled = data.get("encryption", {}).get("enabled", False)
# Get API key hashing enabled from config data directly (under encryption namespace)
# Default: false - rely on file-level encryption for API key protection
api_key_hashing_enabled = (
data.get("encryption", {}).get("api_key_hashing", {}).get("enabled", False)
)
# BREAKING CHANGE: Previously, encryption.enabled=true implicitly enabled API key Argon2id hashing.
# Now, you must explicitly configure encryption.api_key_hashing.enabled=true to enable hashing.
# When encryption.enabled=true but api_key_hashing.enabled=false (default),
# API keys will be stored in plaintext within AES-GCM encrypted files.
if encryption_enabled and not api_key_hashing_enabled:
logger.info(
"API key hashing is disabled while file encryption is enabled. "
"Previously, encryption.enabled=true implicitly enabled API key Argon2id hashing. "
"Now, API keys will be stored in plaintext within AES-GCM encrypted files. "
"To maintain the previous behavior, set encryption.api_key_hashing.enabled=true. "
"See documentation for more details."
)
warn_unknown_config_fields(
data=server_data,
model=ServerConfig,
path_prefix="server",
logger=logger,
)
try:
config = ServerConfig.model_validate(server_data)
except ValidationError as e:
raise ValueError(
f"Invalid server config in {path}:\n"
f"{format_validation_error(root_model=ServerConfig, error=e, path_prefix='server')}"
) from e
return config.model_copy(
update={
"encryption_enabled": encryption_enabled,
"api_key_hashing_enabled": api_key_hashing_enabled,
}
)
_LOCALHOST_HOSTS = {"127.0.0.1", "localhost", "::1"}
def _is_localhost(host: str) -> bool:
"""Return True if *host* resolves to a loopback address."""
return host in _LOCALHOST_HOSTS
def load_bot_gateway_token(config_path: Optional[str] = None) -> str:
"""Load bot gateway token from ov.conf bot.gateway.token."""
path = resolve_config_path(config_path, OPENVIKING_CONFIG_ENV, DEFAULT_OV_CONF)
if path is None:
return ""
data = load_json_config(path)
bot_config = data.get("bot", {})
if not isinstance(bot_config, dict):
return ""
gateway_config = bot_config.get("gateway", {})
if not isinstance(gateway_config, dict):
return ""
return gateway_config.get("token", "") or ""
def validate_server_config(config: ServerConfig) -> None:
"""Validate server config for safe startup.
Validation is delegated to the auth plugin registered for the effective
auth_mode. Built-in plugins (dev, api_key, trusted) preserve the original
validation behaviour.
If auth_mode is not explicitly configured:
- If root_api_key is configured (non-empty): auto-select api_key mode
- If root_api_key is not configured: auto-select dev mode
Raises:
SystemExit: If the configuration is unsafe.
"""
# Check for empty root_api_key
if config.root_api_key == "":
logger.error(
"Invalid server.root_api_key: empty string is not allowed. "
"Set a non-empty server.root_api_key in ov.conf and restart. "
"Only remove this setting if the selected auth mode does not require a root key; "
"trusted and api_key modes require it even on localhost."
)
sys.exit(1)
effective_auth_mode = config.get_effective_auth_mode()
# Ensure built-in plugins are registered before validation.
# If a non-built-in plugin has already claimed a built-in mode name,
# log a security warning and forcefully override it.
from openviking.server.auth.plugins import ApiKeyAuthPlugin, DevAuthPlugin, TrustedAuthPlugin
registry = get_registry()
_BUILTIN_PLUGINS = {
"dev": DevAuthPlugin,
"api_key": ApiKeyAuthPlugin,
"trusted": TrustedAuthPlugin,
}
for mode, plugin_cls in _BUILTIN_PLUGINS.items():
existing = registry.get(mode)
if existing is None:
registry.register(plugin_cls)
elif existing is not plugin_cls:
logger.warning(
"SECURITY: Auth mode %r was registered by %s but is being "
"overridden by the built-in %s.",
mode,
existing.__name__,
plugin_cls.__name__,
)
registry._plugins[mode] = plugin_cls
plugin_cls = registry.get(effective_auth_mode)
if plugin_cls is None:
logger.error(
"Unknown auth_mode: %r. No auth plugin registered for this mode. Registered modes: %s.",
effective_auth_mode,
", ".join(registry.list_modes()),
)
sys.exit(1)
plugin_cls().validate_config(config)