Server Deployment

Deploy OpenViking as a production HTTP service for AI Agents

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

1. 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
     }
   }
   
2. 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)
   
3. Verify Health

   Test that the server is running:

   curl http://localhost:1933/health
   

   Expected response:

   {"status": "ok"}
   

Running in Background

For long-running deployments:

nohup

# 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:

1. 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
   
2. 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:

Add Resource

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

1. 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
   
2. 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
   
3. 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)"
   
4. Install OpenViking

   # Install within virtual environment
   uv pip install openviking --upgrade
   
   # Verify installation
   python -c "import openviking; print(openviking.__version__)"
   

Server Configuration and Launch

1. Create Configuration Directory

   mkdir -p ~/.openviking
   
2. 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
3. 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
   
4. 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

1. 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.

2. System Health Check

   # Check server status
   ov status
   
3. 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