Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
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.
- Open the OpenViking console, sign in to Volcengine, and follow the console's activation steps. See the service description for plans and quotas.
- Obtain an OpenViking API key from the console for the CLI connection in the next step.
- Prepare an agent that can run terminal commands on your machine. In “Ask and verify,” it will use
ovto 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.