MCPInstall

ov-server-operate

by volcengineBackend & APIs

Operate and maintain OpenViking server - configure, install, start, stop, and cleanup the server. Use when need to setup or manage OpenViking service deployment.

Installs
142
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/volcengine/openviking --skill ov-server-operate
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads ov-server-operate automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

OpenViking Server Operations

This guide provides standard operating procedures for deploying, managing, and maintaining OpenViking servers in production environments.

Table of Content

  • Service Configuration
  • Environment Setup with uv
  • Server Startup with nohup
  • Server Shutdown
  • Data Cleanup Procedure
  • Verification and Troubleshooting

Service Configuration

Default Paths and Structure

OpenViking uses the following standard directory structure under ~/.openviking/:

~/.openviking/
├── ov.conf             # Server configuration (required)
├── ovcli.conf          # CLI client configuration
├── ov-venv/            # Virtual environment (created by uv)
├── log/                # Server log directory
│   ├── openviking-server.log   # server stdout log
│   └── openviking.log          # server log
└── data/               # Workspace data (configured in ov.conf)
    ├── ...
    └── ...

Configuration Files

1. Server Config (~/.openviking/ov.conf)

Create the configuration file with at minimum the following configuration. Note 1: Replace the api-key with your own api-key. If you don't have one, ask the user to get one (follow the Volcengine Ark platform guide). Note 2: Replace the root_api_key with your own root-api-key. Ask the user to set one — it will be used for authentication when the CLI connects to the server.

{
  "server": {
    "host": "0.0.0.0",
    "port": 1933,
    "root_api_key": "your-root-api-key"
  },
  "storage": {
    "workspace": "~/.openviking/data/"
  },
  "parsers": {
    "code": {
      "gitlab_domains": ["code.byted.org"],
      "azure_devops_domains": ["ssh.dev.azure.com", "vs-ssh.visualstudio.com"]
    }
  },
  "embedding": {
    "dense": {
        "model": "doubao-embedding-vision-251215",
        "api_key": "your-volcengine-api-key",
        "api_base": "https://ark.cn-beijing.volces.com/api/v3",
        "dimension": 1024,
        "input": "multimodal",
        "provider": "volcengine"
    }
  },
  "vlm": {
    "model": "doubao-seed-1-8-251228",
    "api_key": "your-volcengine-api-key",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "temperature": 0.0,
    "max_retries": 2,
    "provider": "volcengine",
    "thinking": false
  },
  "log": {
    "level": "INFO",
    "output": "file",
    "rotation": true,
    "rotation_days": 3,
    "rotation_interval": "midnight"
  }
}

2. CLI Config (~/.openviking/ovcli.conf)

For client connections from localhost:

{
  "url": "http://localhost:1933",
  "api_key": "your-root-api-key"
}

For remote connections, set the url to the remote server address (for example, the server EIP).

Environment Setup with uv

Step 1: Install uv (if not already installed)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version

Step 2: Create Virtual Environment

Create a dedicated virtual environment at ~/.openviking/ov-venv:

# Create venv with Python 3.10+
cd ~/.openviking
uv venv --python 3.12 ov-venv

Step 3: Activate and Install OpenViking

# Activate the virtual environment
source ~/.openviking/ov-venv/bin/activate

# Install or upgrade to latest openviking
uv pip install --upgrade openviking --force-reinstall

# Verify installation
which openviking-server
openviking-server --version
openviking-server --help

Step 4: Create Log Directory

mkdir -p ~/.openviking/log

Server Startup with nohup

Standard Startup Procedure

# 1. Activate the virtual environment
source ~/.openviking/ov-venv/bin/activate

# 2. Ensure log directory exists
mkdir -p ~/.openviking/log

# 3. Start server with nohup
nohup openviking-server \
    > ~/.openviking/log/openviking-server.log 2>&1 &

# 4. Save PID for later reference
echo $! > ~/.openviking/server.pid

# 5. Verify startup after 10 secs
sleep 10
curl -s http://localhost:1933/health

Verify Server is Running

# Method 1: Check health endpoint
curl http://localhost:1933/health
# Expected: {"status": "ok"}

# Method 2: Check readiness (includes storage checks)
curl http://localhost:1933/ready

# Method 3: Check process
ps aux | grep openviking-server | grep -v grep

# Method 4: Check log output
tail -10 ~/.openviking/log/openviking-server.log
tail -50 ~/.openviking/log/openviking.log

Server Shutdown

Graceful Shutdown Procedure

# 1. Find the server process
ps aux | grep openviking-server | grep -v grep

# 2. Send SIGTERM for graceful shutdown
# Option A: Using saved PID
if [ -f ~/.openviking/server.pid ]; then
    kill $(cat ~/.openviking/server.pid)
    rm ~/.openviking/server.pid
fi

# Option B: Using pgrep
pkill -f openviking-server

# 3. Wait for process to stop
sleep 3

# 4. Verify it stopped
ps aux | grep openviking-server | grep -v grep || echo "Server stopped successfully"

# 5. If still running, force kill
if pgrep -f openviking-server > /dev/null; then
    echo "Force killing server..."
    pkill -9 -f openviking-server
fi

Data Cleanup Procedure

When to Use This Procedure

Perform full data cleanup in these scenarios:

  1. Version upgrade with incompatible data format
  2. Corrupted or inconsistent data
  3. Need to reset to fresh state
  4. Storage space reclamation

Standard Cleanup Workflow

CRITICAL: ALWAYS BACKUP BEFORE DELETING DATA

# ==========================================
# STEP 1: STOP THE SERVER FIRST
# ==========================================
echo "Step 1: Stopping OpenViking Server..."
if pgrep -f openviking-server > /dev/null; then
    pkill -f openviking-server
    sleep 3
    if pgrep -f openviking-server > /dev/null; then
        pkill -9 -f openviking-server
        sleep 1
    fi
fi

# Verify server is stopped
if pgrep -f openviking-server > /dev/null; then
    echo "ERROR: Server still running! Cannot proceed."
    exit 1
fi
echo "✓ Server stopped"

# ==========================================
# STEP 2: CREATE BACKUP (REQUIRED)
# ==========================================
echo ""
echo "Step 2: Creating backup..."
BACKUP_DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=~/.openviking/backup_${BACKUP_DATE}

mkdir -p ${BACKUP_DIR}

# Backup config files
cp ~/.openviking/ov.conf ${BACKUP_DIR}/ 2>/dev/null || true
cp ~/.openviking/ovcli.conf ${BACKUP_DIR}/ 2>/dev/null || true

# Backup workspace (if exists)
WORKSPACE=$(python3 -c '
import json
import os
config_path = os.path.expanduser("~/.openviking/ov.conf")
if os.path.exists(config_path):
    with open(config_path) as f:
        cfg = json.load(f)
        ws = cfg.get("storage", {}).get("workspace", "./data")
        print(os.path.expanduser(ws))
' 2>/dev/null || echo "~/.openviking/data")

if [ -d "${WORKSPACE}" ]; then
    echo "Backing up workspace: ${WORKSPACE}"
    tar -czf ${BACKUP_DIR}/workspace_backup.tar.gz -C $(dirname ${WORKSPACE}) $(basename ${WORKSPACE})
fi

# Backup log
if [ -d ~/.openviking/log ]; then
    cp -r ~/.openviking/log ${BACKUP_DIR}/ 2>/dev/null || true
fi

echo "✓ Backup created at: ${BACKUP_DIR}"
ls -lh ${BACKUP_DIR}/

# ==========================================
# STEP 3: CONFIRM DELETION
# ==========================================
echo ""
echo "=========================================="
echo "WARNING: ABOUT TO DELETE ALL DATA!"
echo "=========================================="
echo "Workspace to delete: ${WORKSPACE}"
echo "Backup location: ${BACKUP_DIR}"
echo ""
read -p "Type 'DELETE' to confirm data removal: " CONFIRM

if [ "${CONFIRM}" != "DELETE" ]; then
    echo "Cleanup cancelled. Backup preserved at ${BACKUP_DIR}"
    exit 0
fi

# ==========================================
# STEP 4: DELETE DATA
# ==========================================
echo ""
echo "Step 4: Deleting data..."

# Delete workspace
if [ -d "${WORKSPACE}" ]; then
    echo "Deleting workspace: ${WORKSPACE}"
    rm -rf "${WORKSPACE}"
fi

# Optional: Delete old log (uncomment if needed)
# echo "Deleting old log..."
# rm -rf ~/.openviking/log/*

# Cleanup any temporary files
rm -f ~/.openviking/server.pid

echo "✓ Data deleted successfully"

# ==========================================
# STEP 5: COMPLETION
# ==========================================
echo ""
echo "=========================================="
echo "Cleanup Complete!"
echo "=========================================="
echo "Backup preserved at: ${BACKUP_DIR}"
echo ""
echo "Next steps:"
echo "1. Reconfigure ov.conf if needed"
echo "2. Start the server: openviking-server"
echo "3. Verify with: curl http://localhost:1933/health"
echo ""
echo "To restore from backup:"
echo "  tar -xzf ${BACKUP_DIR}/workspace_backup.tar.gz -C $(dirname ${WORKSPACE})"

Quick Cleanup (for Development Only)

# WARNING: Only use in development!
# No backup created - data loss guaranteed!

# 1. Stop server
pkill -f openviking-server
sleep 2
pkill -9 -f openviking-server 2>/dev/null || true

# 2. Delete workspace (adjust path as needed)
rm -rf ~/.openviking/data

# 3. Cleanup PID and temp files
rm -f ~/.openviking/server.pid

echo "Quick cleanup complete"

Verification and Troubleshooting

Health Check Verification

# Basic health check (always available)
curl http://localhost:1933/health
# Expected: {"status": "ok"}

# Readiness check (verifies all components)
curl http://localhost:1933/ready
# Expected: {"status": "ready", "checks": {"agfs": "ok", "vectordb": "ok", "api_key_manager": "ok"}}

# System status via CLI (~/.openviking/ovcli.conf should be configured)
ov status

Common Issues and Solutions

Issue: Server won't start

Check:

# 1. Check if port is in use
lsof -i :1933
netstat -tulpn | grep 1933

# 2. Check log for errors
tail -10 ~/.openviking/log/openviking-server.log
tail -100 ~/.openviking/log/openviking.log


# 3. Verify config file is valid JSON
python3 -c 'import json, os; json.load(open(os.path.expanduser("~/.openviking/ov.conf"))); print("Config is valid")'

# 4. Verify virtual environment
source ~/.openviking/ov-venv/bin/activate
which openviking-server
pip list | grep openviking

Solution:

# If port conflict: kill the process or use different port
lsof -ti :1933 | xargs kill -9 2>/dev/null || true

# Or start on different port
nohup openviking-server --port 1934 > ~/.openviking/log/openviking-server.log 2>&1 &

Issue: API Key Errors

Check:

# Verify API keys in config
python3 -c '
import json, os
cfg = json.load(open(os.path.expanduser("~/.openviking/ov.conf")))
print("Embedding provider:", cfg.get("embedding", {}).get("dense", {}).get("provider"))
print("VLM provider:", cfg.get("vlm", {}).get("provider"))
print("API keys set:", bool(cfg.get("embedding", {}).get("dense", {}).get("api_key")), bool(cfg.get("vlm", {}).get("api_key")))
'

Solution: Verify API keys are correct and have the required permissions. Check network connectivity to the model provider endpoints. Ensure API keys are not expired.

Prerequisites

  • Python 3.10+ installed
  • uv package manager available
  • Sufficient disk space for workspace and log
  • API keys for embedding and VLM models configured
  • Network access to model providers (if using cloud models)

FAQ

What does the ov-server-operate skill do?

Operate and maintain OpenViking server - configure, install, start, stop, and cleanup the server. Use when need to setup or manage OpenViking service deployment.

How do I install ov-server-operate?

Run npx skills add https://github.com/volcengine/openviking --skill ov-server-operate in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ov-server-operate/ (personal) or .claude/skills/ov-server-operate/ (project).

Which AI agents can use ov-server-operate?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is ov-server-operate safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains ov-server-operate?

It is published by volcengine in volcengine/openviking. It has 142 recorded installs.

More from volcengine/openviking

View all →

openviking

volcengine/openviking

Activate when the user asks about any repository listed in the system prompt under 'OpenViking — Indexed Code Repositories', or when they ask about an external library, framework, or project that may have been indexed. Also activate when the user wants to add, remove, or manage repos. Always search the local codebase first before using this skill.

AI & Agents895 installs

ov-experience-memory

volcengine/openviking

Retrieve and apply OpenViking Experience memories through the Agent runtime's generic OpenViking search and read tools. Use before or during executable, multi-step, or tool-based work such as coding, file or data changes, configuration, deployment, workflow execution, and failure recovery when prior operational guidance could improve reliability. Do not use for casual chat or simple factual questions.

DevOps & Cloud580 installs

openviking-memory

volcengine/openviking

Recall and persist long-term memory through the OpenViking MCP tools. Use at the start of any substantive task (coding, configuration, debugging, multi-step or tool-based work) to retrieve relevant prior knowledge with find/search/read, and during or after work to persist durable facts, preferences, decisions, and lessons with remember. Do not use for casual chat or simple factual questions the model can answer directly.

AI & Agents507 installs

cron

volcengine/openviking

Schedule reminders and recurring tasks.

217 installs

memory-recall

volcengine/openviking

Open the skill to read its SKILL.md instructions.

206 installs

github-proxy

volcengine/openviking

GitHub 国内访问加速 skill，使用 githubproxy.cc 代理加速 GitHub 仓库克隆、文件下载、Raw 文件访问等操作。使用场景：(1) 需要 git clone GitHub 仓库时加速，(2) 下载 GitHub Release 文件、Raw 文件、Archive 压缩包时加速，(3) 任何需要访问 GitHub 资源但速度慢的场景

Code Quality & Workflow170 installs

Popular backend & apis skills

View category →

find-skills

vercel-labs/skills

Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

OfficialBackend & APIs4.1M installs

entra-app-registration

microsoft/azure-skills

Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.

OfficialBackend & APIs566.7K installs

google-agents-cli-adk-code

google/agents-cli

This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).

Backend & APIs514.8K installs

embedded-captions

heygen-com/hyperframes

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

Backend & APIs453.3K installs

entra-agent-id

microsoft/azure-skills

Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).

OfficialBackend & APIs336.6K installs

neon

neondatabase/agent-skills

Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.

Backend & APIs237.1K installs