Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

10.9 KB
Raw Blame

Quickstart

To answer questions about your project, an AI agent first needs to find relevant material and read the source. OpenViking is a context database for agents: it stores and retrieves that material so the agent can ground its answers in your sources.

In this walkthrough, you will import fictional Lighthouse project notes, ask an agent about feedback collection, and open its citations to check the answer. Choose Volcengine's cloud service or run OpenViking locally. Both paths take you through import → retrieve and read → generate an answer → verify its sources.

Prerequisites

Choose where to run OpenViking, then prepare the corresponding tools:

Option When to choose it What to prepare
Volcengine cloud service Use a managed service and ask questions through an existing agent Node.js/npm, a Volcengine account, and an agent that can run terminal commands on your machine
Local service Run OpenViking on your computer with its built-in agent, VikingBot Node.js/npm, uv, Python, and model credentials

Install Node.js

Both paths use the ov CLI to work with your sources. Open the Node.js download page, select an LTS release for your operating system, and follow its installer or command instructions. npm is included with Node.js.

Reopen your terminal after installation and confirm that both commands print a version:

node --version
npm --version

For the cloud service, continue to Set up the service.

Prepare the local runtime

The local service uses uv to install OpenViking and Python to run it. The commands below use a macOS / Linux terminal. For other systems, see the uv installation guide and server deployment.

Install uv first:

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

Reopen your terminal and confirm that uv is available:

uv --version

Then install Python 3.13 for the service:

uv python install 3.13

You can use an existing Python 3.13 installation. Other installation options are available on the Python download page and in the uv Python guide.

Prepare credentials for two models: an embedding model for indexing and retrieval, and a VLM with tool-call support for content understanding and VikingBot answers. For each, you need a model name, endpoint, and API key. Follow the Volcengine model activation guide to obtain these details. With Agent Plan, choose a model and endpoint supported by your plan. Importing sources and generating answers invoke models and incur charges according to your provider's pricing.

Set up the service

Complete one of the following paths, then continue to Connect the CLI.

Volcengine cloud service

The cloud service runs OpenViking and processes your sources. Your computer only needs the client tools.

  1. Open the OpenViking console, sign in to Volcengine, and follow the console's activation steps. See the service description for plans and quotas.
  2. Obtain an OpenViking API key from the console for the CLI connection in the next step.
  3. Prepare an agent that can run terminal commands on your machine. In “Ask and verify,” it will use ov to retrieve cloud-hosted sources and generate an answer. See CLI basics for agent access.

Once you have the API key, continue to Connect the CLI.

Local service

Install OpenViking with VikingBot to manage sources and answer questions on your machine:

uv tool install --python 3.13 "openviking[bot]" --upgrade

Run the setup wizard. Choose local access and enter the embedding and VLM settings you prepared. VikingBot uses this VLM configuration by default.

openviking-server init

Check the model and service configuration. If the check reports an error, correct the indicated setting and run it again:

openviking-server doctor

Once the checks pass, start the service with VikingBot. Keep this terminal running and use another terminal for the remaining commands.

openviking-server --with-bot

In the new terminal, check that both the data service and agent are ready:

curl -f http://127.0.0.1:1933/health
curl -f http://127.0.0.1:1933/bot/v1/health

Continue when the first response reports healthy: true and the Bot response reports status: healthy.

Connect the CLI

Install the CLI to import, retrieve, and read sources from your terminal. Skip installation if ov is already available.

npm install -g @openviking/cli

Set the interface language and open the connection wizard:

ov language en
ov config

Add a connection using the settings for your chosen path, then save and activate it:

Option Connection type Settings
Volcengine cloud service OpenViking Service Use the service address provided by the wizard and enter the API key from the console
Local service Custom Set the URL to http://127.0.0.1:1933; leave the key empty for default local mode

If your local service already has authentication configured, use its User/Admin key. See Authentication for setup details.

Check the active connection before importing:

ov health

Import the sample

Download the Lighthouse notes, save them as lighthouse.en.md, and open your terminal in that directory. The notes describe the pilot's network constraints, feedback collection, and open questions.

Import the file into a separate demo directory. --wait waits for processing to finish. For a repeat run, replace lighthouse-demo with a new directory name and use that same name in subsequent commands.

ov add-resource ./lighthouse.en.md --to viking://resources/lighthouse-demo --wait

Once processing succeeds, inspect the imported files:

ov tree viking://resources/lighthouse-demo

If waiting times out, run ov task status <task_id> with the returned task ID to check progress. Continue after completion. If the task fails, correct the model or connection settings indicated by the error before retrying. See Background tasks for task states.

Ask and verify

Retrieve and read a source

Find the material about feedback collection:

ov find "How does the first version of Lighthouse collect feedback?" --uri viking://resources/lighthouse-demo

The results include URIs for matching content. Copy a source file URI, replace the placeholder below, and read the original text:

ov read "<source-file-uri>"

Once you can read sections such as "Pilot environment" and "Feedback collection," ask an agent to use those sources.

Generate an answer

Cloud service: Send the following task to an agent that can run local terminal commands. It should use the CLI connection you just configured. If the agent runs on another machine or in a separate container, connect the CLI in that environment first.

Use the locally configured ov CLI to answer a question from project sources in OpenViking.
Run ov health to check the connection, then run:
ov find "How does the first version of Lighthouse collect feedback?" --uri viking://resources/lighthouse-demo
Use ov read to open the relevant original text from the results, then answer:
How should the first version of Lighthouse collect user feedback, and what must be prepared?
Use only sources in that directory. Cite the full source file viking:// URI for each
key conclusion, and identify anything the sources do not specify.

Local service: Use ov chat to ask the running VikingBot the same question. It will use its retrieval and reading tools:

ov chat -m "Use only the sources under viking://resources/lighthouse-demo. Run a semantic search for the question, then read the relevant original text and answer: How should the first version of Lighthouse collect user feedback, and what must be prepared? Cite the full source file viking:// URI for each key conclusion. Explicitly identify anything the sources do not specify."

Check the supporting evidence

Open the source files cited in the answer and compare the following facts. Wording can vary; check that each conclusion agrees with the original text.

Expected conclusion Supporting section
Save feedback locally; the pilot administrator exports it weekly to the project owner Feedback collection
Prepare an offline installation package and a local storage directory Pilot environment
No cloud synchronization in the first version; future support is undecided Feedback collection

If a conclusion lacks a citation, ask the agent to add it and check the source again. Then ask when the pilot ends and check that the answer identifies the date as undecided.

You have now imported sources, retrieved and read them, and checked an answer against its citations. Try the same workflow with your own material next.

Troubleshooting

Symptom Next step
uv, node, or ov is not found after installation Reopen the terminal. If needed, follow the relevant installation guide to check the command path.
ov health cannot connect Check the active connection, service URL, and API key in ov config. For a local service, also check its running terminal.
Bot health returns 503 Confirm the service started with --with-bot; inspect the service terminal and VikingBot logs.
Import fails or retrieval is empty Inspect the returned task, model availability, processing completion, and target URI.
A model returns UnsupportedModel Check that the model, endpoint, and plan match; see the model activation guide.
The agent cannot run ov Check ov --version and ov health in the agent's terminal, then complete installation and connection setup there.

Next steps

Continue to Resource retrieval to try questions requiring multiple sources or information missing from the material. Use Evaluation to record results on your own tasks.