Server Deployment

Overview

OpenViking can be deployed as a standalone HTTP server, providing persistent, high-performance context support for your AI Agents. This enables:

Centralized Context

Share context across multiple agents and applications

Production Ready

Built on FastAPI and Uvicorn for high performance

Multi-client Support

Python SDK, Rust CLI, and REST API access

Scalable

Deploy on cloud infrastructure for high availability

Prerequisites

Before deploying OpenViking server, ensure you have:

OpenViking installed: pip install openviking --upgrade
Model configuration ready (VLM and embedding models)
Server configuration file at ~/.openviking/ov.conf

See the Quick Start guide for installation and configuration details.

Starting the Server

Basic Usage

Prepare Configuration

Create your server configuration file at ~/.openviking/ov.conf:

~/.openviking/ov.conf

{
  "storage": {
    "workspace": "/home/your-name/openviking_workspace"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"
  },
  "embedding": {
    "dense": {
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "your-embedding-api-key",
      "provider": "volcengine",
      "dimension": 1024,
      "model": "doubao-embedding-vision-250615"
    },
    "max_concurrent": 10
  },
  "vlm": {
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "your-vlm-api-key",
    "provider": "volcengine",
    "model": "doubao-seed-2-0-pro-260215",
    "max_concurrent": 100
  }
}

Start the Server

Launch OpenViking server:

# Use default config at ~/.openviking/ov.conf
openviking-server

# Or specify custom config location
openviking-server --config /path/to/ov.conf

# Override host and port
openviking-server --host 0.0.0.0 --port 8000

You should see:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:1933 (Press CTRL+C to quit)

Verify Health

Test that the server is running:

curl http://localhost:1933/health

Expected response:

{"status": "ok"}

Running in Background

For long-running deployments:

# Run with nohup
nohup openviking-server > /data/log/openviking.log 2>&1 &

# Check process
ps aux | grep openviking-server

# View logs
tail -f /data/log/openviking.log

Client Connections

Python SDK

Connect to OpenViking server using the Python SDK:

import openviking as ov

# Connect to server
client = ov.SyncHTTPClient(url="http://localhost:1933")

try:
    client.initialize()
    
    # Add a resource
    result = client.add_resource(
        path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
    )
    root_uri = result["root_uri"]
    print(f"Resource added: {root_uri}")
    
    # Wait for processing
    client.wait_processed()
    
    # Search
    results = client.find("what is openviking", target_uri=root_uri)
    for r in results.resources:
        print(f"  {r.uri} (score: {r.score:.4f})")
        
finally:
    client.close()

With Authentication

If your server has authentication enabled:

client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="your-api-key",
    agent_id="my-agent"
)

Async Client

For async applications:

import asyncio
import openviking as ov

async def main():
    client = ov.AsyncHTTPClient(url="http://localhost:1933")
    
    try:
        await client.initialize()
        
        # Add resource
        result = await client.add_resource(
            path="https://example.com/doc.md"
        )
        
        # Search
        results = await client.find("search query")
        print(f"Found {results.total} results")
        
    finally:
        await client.close()

asyncio.run(main())

Rust CLI

Configure the Rust CLI to connect to your server:

Create CLI Configuration

Create ~/.openviking/ovcli.conf:

~/.openviking/ovcli.conf

{
  "url": "http://localhost:1933",
  "timeout": 60.0,
  "output": "table"
}

Or set environment variable:

export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf

Use CLI Commands

# Check system health
ov status

# Add a resource
ov add-resource https://github.com/volcengine/OpenViking

# List resources
ov ls viking://resources/

# Tree view
ov tree viking://resources/volcengine -L 2

# Semantic search
ov find "what is openviking"

# Text search within path
ov grep "openviking" --uri viking://resources/volcengine

REST API

Access OpenViking directly via HTTP:

curl -X POST http://localhost:1933/api/v1/resources \
  -H "Content-Type: application/json" \
  -d '{
    "path": "https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
  }'

Cloud Deployment: Volcengine ECS

For production deployments, we recommend Volcengine Elastic Compute Service (ECS) with veLinux for optimal performance.

Instance Provisioning

Recommended specifications for Volcengine ECS Console:

Component	Recommendation	Notes
Image	veLinux 2.0 (CentOS Compatible)	Enable “Security Hardening”
Instance Type	Compute Optimized c3a (2 vCPU, 4GiB+)	For basic inference and retrieval
Storage	256 GiB Data Disk	For vector data persistence
Networking	Configure as needed	Open TCP 1933 (or custom port)

Environment Setup

Mount Data Disk

After instance creation, mount the data disk:

# Create mount point
mkdir -p /data

# Configure auto-mount using UUID
cp /etc/fstab /etc/fstab.bak
DISK_UUID=$(blkid -s UUID -o value /dev/vdb)

if [ -z "$DISK_UUID" ]; then
    echo "ERROR: /dev/vdb UUID not found"
else
    echo "UUID=${DISK_UUID} /data ext4 defaults,nofail 0 0" >> /etc/fstab
    mount -a
    echo "Mount successful. Current disk status:"
    df -Th /data
fi

Install Dependencies

# Install system packages
yum install -y curl git tree

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Configure environment
echo 'source $HOME/.cargo/env' >> ~/.bashrc
source ~/.bashrc

# Verify installation
uv --version

Create Virtual Environment

# Create virtual environment on data disk
cd /data
uv venv ovenv --python 3.11

# Activate environment
source /data/ovenv/bin/activate

# Verify
echo "Python path: $(which python)"
echo "Python version: $(python --version)"

Install OpenViking

# Install within virtual environment
uv pip install openviking --upgrade

# Verify installation
python -c "import openviking; print(openviking.__version__)"

Server Configuration and Launch

Create Configuration Directory

mkdir -p ~/.openviking

Create Configuration File

vim ~/.openviking/ov.conf

Add your configuration (see Basic Usage section above for template).

Vim Quick Reference:

Press i to enter Insert mode
Paste your configuration
Press Esc then type :wq to save and exit

Launch Server

# Activate environment
source /data/ovenv/bin/activate

# Create log directory
mkdir -p /data/log/

# Launch with nohup
nohup openviking-server > /data/log/openviking.log 2>&1 &

# Check process
ps aux | grep openviking-server

To stop the service:

pkill openviking
pkill agfs

Verify Server Status

# Check process
ps aux | grep openviking-server

# View logs
tail -f /data/log/openviking.log

# Test health endpoint
curl http://localhost:1933/health

Production Testing

Configure Local Client

On your local machine, create ~/.openviking/ovcli.conf:

{
  "url": "http://YOUR-SERVER-IP:1933",
  "timeout": 60.0,
  "output": "table"
}

Replace YOUR-SERVER-IP with your ECS instance’s public IP.

System Health Check

# Check server status
ov status

Functional Testing

# Upload a test resource
ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md

# List resources
ov ls viking://resources

# Test retrieval
ov find "what is openviking"

# Tree view
ov tree viking://resources/ -L 2

Docker Deployment (Optional)

For containerized deployments:

Dockerfile

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    git \
    && rm -rf /var/lib/apt/lists/*

# Install OpenViking
RUN pip install openviking --upgrade

# Create workspace directory
RUN mkdir -p /data/openviking_workspace

# Copy configuration
COPY ov.conf /root/.openviking/ov.conf

# Expose port
EXPOSE 1933

# Run server
CMD ["openviking-server", "--host", "0.0.0.0", "--port", "1933"]

Build and run:

# Build image
docker build -t openviking-server .

# Run container
docker run -d \
  --name openviking \
  -p 1933:1933 \
  -v /path/to/data:/data/openviking_workspace \
  openviking-server

# Check logs
docker logs -f openviking

# Health check
curl http://localhost:1933/health

Configuration Options

Server Configuration Reference

{
  "storage": {
    "workspace": "/path/to/workspace",  // Data storage location
    "agfs": {
      "port": 1833  // AGFS internal port (optional)
    }
  },
  "log": {
    "level": "INFO",      // DEBUG, INFO, WARNING, ERROR
    "output": "stdout"    // stdout or file
  },
  "embedding": {
    "dense": {
      "provider": "volcengine",   // volcengine, openai, jina
      "model": "model-name",
      "api_key": "your-key",
      "api_base": "endpoint-url",
      "dimension": 1024,
      "input": "multimodal"       // Optional: for vision models
    },
    "max_concurrent": 10
  },
  "vlm": {
    "provider": "volcengine",     // volcengine, openai, litellm
    "model": "model-name",
    "api_key": "your-key",
    "api_base": "endpoint-url",
    "max_concurrent": 100,
    "max_retries": 2
  }
}

Environment Variables

Variable	Description	Default
`OPENVIKING_CONFIG_FILE`	Path to server config file	`~/.openviking/ov.conf`
`OPENVIKING_CLI_CONFIG_FILE`	Path to CLI config file	`~/.openviking/ovcli.conf`

Monitoring and Maintenance

Health Monitoring

# Health endpoint
curl http://localhost:1933/health

# System status (via CLI)
ov status

# Observer API (detailed metrics)
curl http://localhost:1933/api/v1/observer/system

Log Management

# View real-time logs
tail -f /data/log/openviking.log

# Search logs
grep "ERROR" /data/log/openviking.log

# Rotate logs (recommended for production)
# Add to /etc/logrotate.d/openviking
/data/log/openviking.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
}

Resource Management

# Check disk usage
df -h /data

# Check memory usage
free -h

# Monitor processes
top -p $(pgrep -f openviking-server)

Security Considerations

Production Security Checklist:

Configure firewall rules to restrict access
Use HTTPS with reverse proxy (nginx/caddy)
Enable API authentication
Regularly update OpenViking and dependencies
Monitor logs for suspicious activity
Backup workspace data regularly
Use environment variables for sensitive credentials

Reverse Proxy Example (Nginx)

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:1933;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Next Steps

API Reference

Complete API documentation

Authentication

Secure your OpenViking server

Monitoring

Monitor your production deployment

Examples

Production integration examples

Get Started

Core Concepts

Guides

Integrations

Overview

Centralized Context

Production Ready

Multi-client Support

Scalable

Prerequisites

Starting the Server

Basic Usage

Running in Background

Client Connections

Python SDK

With Authentication

Async Client

Rust CLI

REST API

Cloud Deployment: Volcengine ECS

Instance Provisioning

Environment Setup

Server Configuration and Launch

Production Testing

Docker Deployment (Optional)

Configuration Options

Server Configuration Reference

Environment Variables

Monitoring and Maintenance

Health Monitoring

Log Management

Resource Management

Security Considerations

Reverse Proxy Example (Nginx)

Next Steps

API Reference

Authentication

Monitoring

Examples

Get Started

Core Concepts

Guides

Integrations

​Overview

Centralized Context

Production Ready

Multi-client Support

Scalable

​Prerequisites

​Starting the Server

​Basic Usage

​Running in Background

​Client Connections

​Python SDK

​With Authentication

​Async Client

​Rust CLI

​REST API

​Cloud Deployment: Volcengine ECS

​Instance Provisioning

​Environment Setup

​Server Configuration and Launch

​Production Testing

​Docker Deployment (Optional)

​Configuration Options

​Server Configuration Reference

​Environment Variables

​Monitoring and Maintenance

​Health Monitoring

​Log Management

​Resource Management

​Security Considerations

​Reverse Proxy Example (Nginx)

​Next Steps

API Reference

Authentication

Monitoring

Examples

Overview

Prerequisites

Starting the Server

Basic Usage

Running in Background

Client Connections

Python SDK

With Authentication

Async Client

Rust CLI

REST API

Cloud Deployment: Volcengine ECS

Instance Provisioning

Environment Setup

Server Configuration and Launch

Production Testing

Docker Deployment (Optional)

Configuration Options

Server Configuration Reference

Environment Variables

Monitoring and Maintenance

Health Monitoring

Log Management

Resource Management

Security Considerations

Reverse Proxy Example (Nginx)

Next Steps