/install-openviking

description: Install OpenViking persistent memory with its native HTTP MCP endpoint and register it in the active AI client
userOnly: true

/install-openviking — install OpenViking persistent memory

Install the official OpenViking package and connect its built-in HTTP MCP endpoint. Use the server id `openviking`. A separate MCP proxy is unnecessary.

Memory routing and triage scope follow `content/rules/project-memory.md` after `.dev.env` `TOOL_*` policy. Installation preserves every provider choice; `TOOL_OPENVIKING=off` allows explicitly requested setup checks but still excludes ordinary memory use. A client config entry alone does not prove callable tools. Connecting this provider does not enable or disable another.

Official references (recheck the selected release before installation):

• [Agent setup](https://docs.openviking.ai/en/getting-started/04-setup-for-agent)
• [Server deployment and readiness](https://docs.openviking.ai/en/getting-started/03-quickstart-server)
• [MCP integration and tool reference](https://docs.openviking.ai/en/guides/06-mcp-integration)
• [Source and releases](https://github.com/volcengine/OpenViking)

1. Detect and choose deployment

Load `content/rules/mcp-deployment.md`. Local deployment remains the ordinary path; when Docker is selected, also offer an optional shared Debian/Ubuntu Docker Engine host and DNS/IP instead of loopback. Reuse an existing target choice. For a new service the agent selects a free host port on that host automatically; for an existing endpoint preserve its address and port. Docker Desktop is not required on clients of a remote service.

Inspect the active client's MCP entries, exposed OpenViking tools, any existing installation manifest, package/process or Docker container, and the configured health endpoint. The defaults are `http://127.0.0.1:1933/health` and `http://127.0.0.1:1933/mcp`. Remote installations do not need a local Python package.

Reuse an existing healthy endpoint. Preserve existing config, credentials, workspace and unrelated MCP entries. A stopped server is not evidence that its data can be replaced; inspect it before repair or update. Do not start another process against an existing workspace or occupied port.

For a new installation, prefer the published Python package in an isolated environment, including on Windows. Use an existing remote endpoint when supplied; use the official Docker image when Docker deployment is selected. Ask only for missing deployment and model settings, reusing the user's existing choice from `/installtools`.

Collect the configuration path, durable absolute `storage.workspace`, and the provider/model/endpoint/auth settings for both `embedding.dense` and `vlm`. Do not guess model names, dimensions or credentials. Use the official configuration guide for the chosen providers; an LLM account alone does not confirm embedding support. For local models, the official `openviking-server init` wizard can configure supported providers.

Default local root: `~/.openviking` (resolved to an absolute path on the host), containing `ov.conf`, `data/`, `.venv/`, logs and a secret-free `install.manifest.json`. Offer another absolute root when needed. Keep secrets and memory data outside source control; protect config permissions and never print keys. Do not overwrite an existing `ov.conf` with wizard defaults.

2. Install and configure the local package

Check the current release's supported Python version and available wheel for this OS/architecture. Prefer prebuilt artifacts; do not add native build toolchains automatically if a wheel is unavailable. Offer a compatible Python environment or the Docker option instead.

For a fresh Windows installation, use the confirmed Python executable and root; the following assumes `python` resolves to that executable:

$ovRoot = Join-Path ([Environment]::GetFolderPath('UserProfile')) '.openviking'
$ovVenv = Join-Path $ovRoot '.venv'
New-Item -ItemType Directory -Path $ovRoot -Force | Out-Null
python -m venv "$ovVenv"
if ($LASTEXITCODE -ne 0) { throw 'Failed to create the OpenViking environment' }
$ovPython = Join-Path $ovVenv 'Scripts/python.exe'
& $ovPython -m pip install --upgrade --only-binary=openviking openviking
if ($LASTEXITCODE -ne 0) { throw 'Failed to install OpenViking' }
$ovServer = Join-Path $ovVenv 'Scripts/openviking-server.exe'
$env:OPENVIKING_CONFIG_FILE = Join-Path $ovRoot 'ov.conf'

On Linux/macOS, use the equivalent native shell, `.venv/bin/python` and `.venv/bin/openviking-server` paths. Do not recreate an existing environment during detection.

Create UTF-8 JSON `ov.conf` from the confirmed settings or use `openviking-server init` interactively in the selected environment. Include the absolute `storage.workspace` and provider-specific `embedding.dense` / `vlm` settings. Add optional settings only when required by that provider or requested by the user. Preserve any existing configuration through a targeted merge and retain a protected backup before editing it.

Validate using the selected executable and config environment:

& $ovServer doctor
if ($LASTEXITCODE -ne 0) { throw 'OpenViking configuration or model checks failed' }

Do not claim readiness after installation alone. Resolve missing configuration, authentication or model access before starting the service; report a blocker when a required setting is unavailable.

3. Start and check the server

Bind a local package installation explicitly to loopback. Allocate an available port before launch per the deployment rule; `1933` is only the preferred candidate. Substitute the selected bind address, port and actual health URL in the example. For a background helper on Windows, keep its window hidden and capture logs:

$ovProcess = Start-Process -FilePath $ovServer `
  -ArgumentList @('--host', '127.0.0.1', '--port', '1933') `
  -WorkingDirectory $ovRoot -WindowStyle Hidden -PassThru `
  -RedirectStandardOutput (Join-Pat