openviking-nix

NixOS package for OpenViking — an agent-native context database for AI agents by ByteDance/Volcengine.

Overview

OpenViking organizes agent context (memory, resources, skills) through a virtual filesystem paradigm using viking:// protocol paths. It features tiered context loading (L0/L1/L2), hierarchical RAG, automatic session management, and a chat bot framework.

This repo packages the entire OpenViking stack for NixOS from a 4-language monorepo build:

Component	Language	Output
AGFS server	Go	agfs-server binary
AGFS binding	Go (CGO)	libagfsbinding.so
ov CLI	Rust	ov binary
Vector engine	C++17 / pybind11	engine.cpython-*.so
OpenViking	Python (FastAPI)	Server + client library

Packages

Package	Description
openviking (default)	Full package with server, CLI, vector engine, and all native components
agfs	AGFS server binary + Python binding shared library
ov-cli	OpenViking Rust CLI client

The main openviking package provides 4 binaries: openviking-server, openviking, ov, vikingbot.

Usage

Flake input

inputs.openviking = {
  url = "github:Daaboulex/openviking-nix";
  inputs.nixpkgs.follows = "nixpkgs";
};

Overlay

nixpkgs.overlays = [ inputs.openviking.overlays.default ];
# Provides: pkgs.openviking, pkgs.agfs, pkgs.ov-cli

NixOS module (systemd service)

imports = [ inputs.openviking.nixosModules.default ];

services.openviking = {
  enable = true;
  port = 1933;                 # default
  host = "127.0.0.1";          # default
  dataDir = "/var/lib/openviking";
  # configFile = /path/to/ov.conf;
  openFirewall = false;        # default
};

The service runs with DynamicUser, ProtectSystem=strict, NoNewPrivileges, and other systemd hardening options.

NixOS module options

Option	Type	Default	Description
services.openviking.enable	bool	false	Enable the OpenViking server
services.openviking.package	package	openviking	Package to use
services.openviking.user	string	"openviking"	User account to run as
services.openviking.group	string	"openviking"	Group account to run as
services.openviking.extraGroups	list of string	[]	Extra groups for the service
services.openviking.port	port	1933	Server listen port
services.openviking.host	string	"127.0.0.1"	Server bind address
services.openviking.dataDir	string	"/var/lib/openviking"	Data/workspace directory
services.openviking.settings	null or attrs	null	Declarative ov.conf settings
services.openviking.readOnlyPaths	list of string	[]	Extra paths for the service to read
services.openviking.configFile	null or path	null	Path to ov.conf (defaults to dataDir/ov.conf)
services.openviking.openFirewall	bool	false	Open firewall for server port

Configuration

Declarative Configuration (Recommended)

services.openviking = {
  enable = true;
  user = "user"; # Run as primary user to solve all permission issues for local indexing
  group = "users";
  readOnlyPaths = [ "/home/user/Documents/my-project" ];
  settings = {
    embedding.dense = {
      provider = "openai";
      model = "text-embedding-004";
      api_key = "your-api-key"; # Use sops-nix for security
      api_base = "https://generativelanguage.googleapis.com/v1beta/openai/";
      dimension = 768;
    };
    vlm = {
      provider = "litellm";
      model = "gemini/gemini-2.0-flash";
      api_key = "your-api-key";
    };
  };
};

Note: Declarative configuration will place secrets in the Nix store. Use configFile pointing to a sops-managed file for production use.

Permissions and Indexing

OpenViking runs as a system user with ProtectHome=true by default. To index local directories in /home:

1. Run as your user: Set services.openviking.user = "youruser"; (Easiest and recommended for personal workstations).
2. Alternatively: Keep openviking user, set services.openviking.readOnlyPaths = [ "/path" ];, and ensure permissions are correct on your home directory.

Supports OpenAI, Volcengine, Jina, and LiteLLM (for Claude, Gemini, etc.) providers. See OpenViking docs for the full config reference.

Platform

x86_64-linux only.

Credits

• OpenViking by ByteDance/Volcengine (Apache-2.0)
• Nix packaging by @Daaboulex

License

Apache-2.0 (same as upstream OpenViking).