VikingBot

VikingBot is OpenViking's built-in AI agent. It accepts tasks, calls models and tools, and uses resources, memories, and Skills stored in OpenViking to generate answers. You can chat with it from the command line to organize tasks, query project documents, or follow a reusable workflow.

This guide runs locally. You will start VikingBot, organize a task list, and ask a follow-up in the same session. By the end, you can check that the service is reachable, the model responds, and subsequent messages use the conversation context.

Prerequisites

Prepare the following before you begin:

Requirement	Purpose and setup
uv and Python	Install and run OpenViking and VikingBot. The commands below use Python 3.13; see Prepare the local runtime
Node.js/npm	Install the ov CLI; see Install Node.js
Model credentials	Prepare model names, endpoints, and API keys for an embedding model and a VLM that supports tool calling; see the model setup guide

VikingBot uses the VLM in your OpenViking configuration by default. The embedding model supports later resource retrieval. For Agent Plan, select supported models and endpoints. Model calls incur charges from your chosen service.

If you already started a local service with VikingBot through the quickstart, go to Connect the CLI.

Start the service

Install OpenViking and VikingBot to enable resource management and agent conversations locally:

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

For a first-time setup, run the initialization wizard, choose local access, and enter your model settings. If you already have a configuration, proceed to the configuration check.

openviking-server init

Check the model and service configuration. If the check reports errors, correct the indicated settings and check again:

openviking-server doctor

If your existing service uses API key authentication, first follow Authentication to configure the Bot connection identity and prepare the appropriate User/Admin Key for the CLI.

After the check passes, start OpenViking and VikingBot together. The --with-bot flag enables the agent conversation endpoint. Keep this terminal running and use another terminal for subsequent commands. If a local service is already running without Bot, stop it in its original terminal before starting it with the command below.

openviking-server --with-bot

The remaining commands use the default address, http://127.0.0.1:1933.

Connect the CLI

Install the CLI in a new terminal. If ov is already available, proceed to connection setup.

npm install -g @openviking/cli

Set the interface language to English and open the connection wizard:

ov language en
ov config

Choose a Custom connection and enter http://127.0.0.1:1933 as the URL. Leave the key empty for the default local mode, or enter your User/Admin Key if authentication is enabled. Save and select this configuration; if the connection already exists, select it directly. See CLI basics for other connection options.

First, check that the CLI can reach the data service:

ov health

The result should include healthy: true. Next, check the Bot endpoint:

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

Once it returns status: healthy, you can start a conversation. The next task also checks that the model can generate a response.

Complete a task

Give VikingBot a fictional task list to organize by completion status. The --session option names the conversation so you can continue discussing the list later. When repeating the walkthrough, choose a new session name.

ov chat --session bot-review-v1 -m "Fictional task list: source import is complete; citation verification and demo rehearsal are pending. Organize a brief completed and pending list."

The response should list source import as complete, with citation verification and demo rehearsal pending. Compare the states with the input; wording and formatting can vary.

Ask a follow-up

Keep the same --session and ask VikingBot to suggest the next step based on the list:

ov chat --session bot-review-v1 -m "Using that list, suggest what to complete first and explain why in one sentence."

You do not need to repeat the list. The response should discuss citation verification or demo rehearsal. For example, it might recommend checking citations first to confirm accuracy before the demo. The suggested order can vary, but its reasoning should use the pending items from the previous turn.

Follow-ups in the same session use the existing conversation context. A new session name starts another conversation. To reuse project background or preferences across sessions, continue to Memory use for memory storage and recall.

Check the result

Check	Expected result
Service connection	Both ov health and the Bot health check succeed
Single task	The response preserves all three tasks and their completion states
Continued conversation	The follow-up uses the previous pending items and explains its recommendation

If the response omits a task or changes its state, point out the difference and ask VikingBot to revise it against the original list.

Troubleshooting

Symptom	What to check
openviking-server or ov is unavailable after installation	Open a new terminal; if the command is still unavailable, check executable paths using the uv or npm installation instructions
The port is already in use	Check for an existing local service; to enable Bot, stop it in its original terminal and restart with --with-bot
ov health cannot connect	Check the current address in ov config and confirm that the service terminal is still running
Bot health returns 503	Confirm that startup included --with-bot and inspect the Bot startup messages in the service logs
Health checks pass but model calls fail	Use the error message to check the model name, endpoint, credentials, and plan support
The follow-up does not use the list	Confirm that both commands use the same --session and CLI identity, and that the first turn returned a complete response

Next steps

Once connection and conversation work, use OpenViking context in your tasks:

Goal	Next step
Answer questions from project documents and verify sources	Resource retrieval
Reuse background and preferences in a new session	Memory use
Apply a consistent workflow to different inputs	Skill use

See the VikingBot guide for chat platforms such as Feishu, standalone debugging, and model configuration. See Bot API to send messages from an application. VikingBot Gateway handles Bot messages and chat channels; the OpenViking gateway provides a model request endpoint for compatible clients.

Finish the trial

Keep the session name to continue the conversation later. Stop the local service with Ctrl+C in its terminal; the CLI conversation endpoint closes with it. To clean up test sessions, identify the corresponding sessions in Studio before deleting them.