Deployment

Deploy OpenViking as a standalone HTTP server for production use

OpenViking can run as a standalone HTTP server, allowing multiple clients to connect over the network.

Quick Start

1. Create Configuration

   Create ~/.openviking/ov.conf with your settings:

   {
     "server": {
       "host": "0.0.0.0",
       "port": 1933,
       "root_api_key": "your-secret-root-key"
     },
     "storage": {
       "workspace": "./data",
       "agfs": { "backend": "local" },
       "vectordb": { "backend": "local" }
     },
     "embedding": {
       "dense": {
         "provider": "volcengine",
         "api_key": "your-embedding-api-key",
         "model": "doubao-embedding-vision-250615",
         "dimension": 1024
       }
     },
     "vlm": {
       "provider": "volcengine",
       "api_key": "your-vlm-api-key",
       "model": "doubao-seed-2-0-pro-260215"
     }
   }
   
2. Start Server

   openviking-server
   

   Or specify a custom config path:

   openviking-server --config /path/to/ov.conf
   
3. Verify

   curl http://localhost:1933/health
   # {"status": "ok"}
   

Command Line Options

Option	Description	Default
--config	Path to ov.conf file	~/.openviking/ov.conf
--host	Host to bind to	0.0.0.0
--port	Port to bind to	1933

Examples

# With default config
openviking-server

# With custom port
openviking-server --port 8000

# With custom config, host, and port
openviking-server --config /path/to/ov.conf --host 127.0.0.1 --port 8000

Deployment Modes

Standalone (Embedded Storage)

Server manages local AGFS and VectorDB:

{
  "storage": {
    "workspace": "./data",
    "agfs": { "backend": "local" },
    "vectordb": { "backend": "local" }
  }
}

Best for development and small deployments. All data is stored locally.

Hybrid (Remote Storage)

Server connects to remote AGFS and VectorDB services:

{
  "storage": {
    "agfs": { 
      "backend": "http", 
      "url": "http://agfs:1833" 
    },
    "vectordb": { 
      "backend": "http", 
      "url": "http://vectordb:8000" 
    }
  }
}

Recommended for production. Enables horizontal scaling and shared storage.

Production Deployment

Systemd Service (Linux)

For Linux systems, use Systemd to manage OpenViking as a service.

1. Create Service File

   Create /etc/systemd/system/openviking.service:

   [Unit]
   Description=OpenViking HTTP Server
   After=network.target
   
   [Service]
   Type=simple
   WorkingDirectory=/var/lib/openviking
   ExecStart=/usr/bin/openviking-server
   Restart=always
   RestartSec=5
   Environment="OPENVIKING_CONFIG_FILE=/etc/openviking/ov.conf"
   
   [Install]
   WantedBy=multi-user.target
   
2. Enable and Start

   # Reload systemd configuration
   sudo systemctl daemon-reload
   
   # Start the service
   sudo systemctl start openviking.service
   
   # Enable service on boot
   sudo systemctl enable openviking.service
   
3. Manage Service

   # Check service status
   sudo systemctl status openviking.service
   
   # View service logs
   sudo journalctl -u openviking.service -f
   
   # Restart service
   sudo systemctl restart openviking.service
   

Docker

OpenViking provides pre-built Docker images:

Docker Run

docker run -d \
  --name openviking \
  -p 1933:1933 \
  -v ~/.openviking/ov.conf:/app/ov.conf \
  -v /var/lib/openviking/data:/app/data \
  --restart unless-stopped \
  ghcr.io/volcengine/openviking:main

Start with Docker Compose:

docker compose up -d

To build the image yourself: docker build -t openviking:latest .

Kubernetes + Helm

The project provides a Helm chart at examples/k8s-helm/.

1. Install with Helm

   helm install openviking ./examples/k8s-helm \
     --set openviking.config.embedding.dense.api_key="YOUR_API_KEY" \
     --set openviking.config.vlm.api_key="YOUR_API_KEY"
   
2. Verify Deployment

   kubectl get pods -l app=openviking
   kubectl logs -f deployment/openviking
   
3. Access Service

   kubectl port-forward svc/openviking 1933:1933
   curl http://localhost:1933/health
   

For detailed cloud deployment with Volcengine TOS + VikingDB + Ark, see examples/cloud/GUIDE.md.

Health Checks

Endpoint	Auth	Purpose
GET /health	No	Liveness probe — returns {"status": "ok"} immediately
GET /ready	No	Readiness probe — checks AGFS, VectorDB, APIKeyManager

Liveness Check

curl http://localhost:1933/health
# {"status": "ok"}

Use /health for Kubernetes liveness probes and /ready for readiness probes.

Connecting Clients

Python SDK

Sync Client

import openviking as ov

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

client.initialize()
results = client.find("how to use openviking")
client.close()

CLI

Create ~/.openviking/ovcli.conf:

{
  "url": "http://localhost:1933",
  "api_key": "your-key",
  "agent_id": "my-agent"
}

Then use the CLI:

ov ls viking://resources/
ov find "what is openviking"

curl

curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
  -H "X-API-Key: your-key"

Cloud Provider Examples

AWS Deployment

S3 + EKS Configuration

{
  "storage": {
    "agfs": {
      "backend": "s3",
      "s3": {
        "bucket": "openviking-data",
        "region": "us-east-1",
        "access_key": "AKIA...",
        "secret_key": "...",
        "use_path_style": false
      }
    },
    "vectordb": {
      "backend": "http",
      "url": "http://vectordb.default.svc.cluster.local:8000"
    }
  }
}

Deploy to EKS:

helm install openviking ./examples/k8s-helm \
  --set openviking.config.storage.agfs.backend=s3 \
  --set openviking.config.storage.agfs.s3.bucket=openviking-data

Volcengine Deployment

TOS + VikingDB Configuration

{
  "storage": {
    "agfs": {
      "backend": "s3",
      "s3": {
        "bucket": "openviking",
        "endpoint": "tos-s3-cn-beijing.volces.com",
        "region": "cn-beijing",
        "access_key": "AK...",
        "secret_key": "...",
        "use_path_style": false
      }
    },
    "vectordb": {
      "backend": "volcengine",
      "name": "context",
      "volcengine": {
        "region": "cn-beijing",
        "ak": "AK...",
        "sk": "..."
      }
    }
  },
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "api_key": "...",
      "model": "doubao-embedding-vision-250615"
    }
  }
}

Security Best Practices

When no root_api_key is configured, authentication is disabled. This is only allowed when binding to localhost (127.0.0.1). The server will refuse to start if host is 0.0.0.0 without authentication.

1. Always Set root_api_key

   {
     "server": {
       "root_api_key": "generated-secure-key-here"
     }
   }
   
2. Use HTTPS in Production

   Place OpenViking behind a reverse proxy (nginx, Caddy) with TLS:

   server {
       listen 443 ssl;
       server_name openviking.example.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;
       }
   }
   
3. Restrict Network Access

   Use firewall rules to restrict access to trusted IPs:

   # Allow only specific IPs
   sudo ufw allow from 10.0.0.0/8 to any port 1933
   sudo ufw deny 1933
   

Monitoring

For health checks and system monitoring, see the Monitoring Guide.

Related Resources

Configuration

Complete configuration reference

Authentication

API key setup and multi-tenant auth

Monitoring

Health checks and observability

Python SDK

Connect with Python