Import and retrieve your first document

OpenViking runs as a server. Connect to it with the standalone ov CLI, import a small document, and retrieve its content. If you use a managed service or someone else's deployment, you only need the CLI.

1. Choose a service

Already have an endpoint? Keep its URL and API key ready and skip to step 2. For a server using API key authentication, use a user/admin key for data access; a root key is for administration. See Authentication.

Otherwise, choose one:

Managed service on Volcengine

Open the OpenViking console and obtain your key from User Management → API Key. The service endpoint is:

https://api.vikingdb.cn-beijing.volces.com/openviking

No server installation or local model configuration is needed. See the product page and service documentation for managed-service usage and limits. Continue to step 2.

Self-host a server

Install uv on the server machine, then install OpenViking:

uv tool install openviking --upgrade
openviking-server init
openviking-server doctor
openviking-server

The setup wizard configures the server's models and writes ~/.openviking/ov.conf. Prepare access to an embedding model and a VLM — Volcengine (Doubao) models are recommended; see the Volcengine Purchase Guide for purchase and activation — then check the configuration with doctor. Keep the server running and use another terminal for the remaining steps.

A single curl confirms the server is up — no client required:

curl http://127.0.0.1:1933/health
# {"status":"ok","healthy":true,...}

The local endpoint is http://127.0.0.1:1933; the default local setup needs no API key. Web Studio is available at /studio. For Docker, persistent storage, and remote access, see Deployment, Model Configuration, and Authentication.

2. Install and connect the CLI

On your client machine, with Node.js and npm installed:

npm install -g @openviking/cli
ov language en
ov config

In the interactive configuration, choose OpenViking Service for Volcengine or Custom for a self-hosted endpoint. Enter the API key and, for a custom service, its URL. Leave the key empty for the default local server. Save and activate the configuration.

The CLI stores the active connection in ~/.openviking/ovcli.conf. This is separate from the server's ov.conf. For multiple endpoints or agent-assisted setup, see CLI Setup.

Verify the connection:

ov health

This checks that the server responds; the import below also exercises model processing and data access.

3. Import a document

This example imports a real team fact: the four GitHub users who take turns owning the weekly OpenViking release. Save the following as ov-release-rotation.md in your current directory:

# OpenViking release rotation

OpenViking ships a new release every Friday.
Release owners rotate in this order: qin-ctx, zhoujh01, ZaynJarvis, t0saki.

Import it into a new resource directory:

ov add-resource ./ov-release-rotation.md --to viking://resources/ov-release-rotation --wait --timeout 120

The CLI uploads the local file automatically. --wait waits for processing; continue after the command succeeds. Without it, save the returned task_id and use ov task status <task_id> until the task is completed. See Background Tasks.

4. Browse and search

ov tree viking://resources/ov-release-rotation
ov overview viking://resources/ov-release-rotation
ov find "Who owns the weekly OpenViking release?" --uri viking://resources/ov-release-rotation

tree lists the imported structure; overview reads its generated summary. find returns relevant context with URIs and scores. The imported file answers the question, so it is the top match. To read a match, pass its returned URI to ov read:

ov read "<returned-file-uri>"

Replace <returned-file-uri> with a file URI from the results, without the angle brackets. For more resource types and retrieval options, see Resources and Retrieval.

Use an SDK

OpenViking also provides Python, TypeScript/JavaScript, and Go SDKs that connect to the same server. See the API Overview for client examples.

Next steps

First confirm that you can read the sample source, then evaluate OpenViking on your tasks using your own sources or conversations. To use it in a daily tool, choose an agent integration. To write your own application, follow the application workflows.