VikingBot

VikingBot is the multi-channel AI agent built into OpenViking. You can use it directly from the command line or run it as a long-lived Gateway connected to Feishu, Slack, Telegram, and other platforms. When connected to OpenViking, it also gains resource retrieval, user memory, experience memory, and session consolidation.

Key Capabilities

• Multiple chat entry points: vikingbot chat, ov chat, HTTP APIs, and multiple chat platforms.
• Agent tools: built-in file, shell, web, image generation, scheduled task, and OpenViking tools.
• Skills and subagents: load Skills on demand and delegate independent work to background subagents.
• Long-term context: recall Resources, Peer Memories, and Experiences from OpenViking, and commit sessions automatically.
• Safer execution: Direct, SRT, OpenSandbox, and AIO Sandbox backends.
• Service deployment: the Gateway provides synchronous chat, SSE streaming, feedback, and an OpenViking API proxy.

Installation

Install from PyPI

pip install "openviking[bot]"

Install from Source

Python 3.11 or later is required. We recommend using uv:

git clone https://github.com/volcengine/OpenViking.git
cd OpenViking
uv venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[bot]"

On Windows, activate the virtual environment with:

.venv\Scripts\activate

Quick Start: Choose Your Scenario

VikingBot supports three primary usage scenarios. They are different entry points for different needs rather than mutually exclusive modes.

Scenario	Best for	Start command	OpenViking
A. OpenViking + Bot together	A complete local experience with resources, memory, and the Agent	openviking-server --with-bot	The Bot uses the OpenViking Server started by this command
B. Debug the Agent locally	Quickly testing the Bot or developing Tools and Skills	vikingbot chat	Optional; without it, the Bot cannot use OpenViking features
C. Unified Gateway entry point	Starting the Bot separately and connecting it to an existing OpenViking Server	vikingbot gateway	May be configured explicitly or omitted

Scenario A: Start OpenViking and the Bot Together

Use this for the complete local experience. OpenViking Server and VikingBot Gateway start together. ov chat first calls OpenViking Server, whose /bot/v1 route forwards the request to VikingBot.

ov chat → OpenViking Server → VikingBot Gateway → Agent

1. Prepare the configuration

Follow the OpenViking quickstart to configure the models and storage required by OpenViking. By default, the Bot inherits the root-level vlm configuration as its Agent model. Configure bot.agents only if the Bot should use a separate model.

In this combined mode, the Bot always uses the OpenViking Server started by the same command and ignores bot.ov_server settings that point to another service. OpenViking Server injects an authenticated request-scoped identity into every Chat request sent to the Bot.

2. Start both services

openviking-server --with-bot

This command starts the current OpenViking Server and a managed VikingBot Gateway. The Bot uses this Server and does not connect to the service named by bot.ov_server.server_url.

3. Configure and use the ov CLI

Run the interactive configuration manager:

ov config

Point the active CLI configuration to OpenViking Server, for example http://127.0.0.1:1933. If the Server requires authentication, also enter the caller's User/Admin API Key. Then run:

ov chat
ov chat -m "Remember that I prefer concise answers"
ov find "my response preferences"

The identity flow is:

• ovcli.conf.api_key represents the current caller.
• OpenViking Server validates the identity and passes a request-scoped connection to the Bot.
• The request identity takes priority over any process-level default identity, preventing multiple callers from sharing one Bot user.

Scenario B: Debug the Agent Locally

Use this to try VikingBot quickly or develop Agents, Tools, and Skills. vikingbot chat starts the Agent in the current process. It does not require a running Gateway and does not use ovcli.conf as the Bot configuration.

1. Configure a model

Edit ~/.openviking/ov.conf:

{
  "bot": {
    "agents": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "api_key": "<your-model-api-key>",
      "max_tokens": 8192
    }
  }
}

Alternatively, configure only the root-level vlm section. VikingBot inherits its model, provider, API key, API base, timeout, and output-token settings. bot.agents.max_tokens is optional; when omitted, VikingBot lets the model provider choose the output limit. A max_tokens value on an individual credential overrides the Agent-level value.

2. Start chatting

# Send one message
vikingbot chat -m "Summarize the structure of the current project"

# Start an interactive multi-turn conversation
vikingbot chat

# Use a specific session
vikingbot chat --session my-session

If no OpenViking Server is available, VikingBot runs in standalone mode. File, shell, web, and Skill capabilities remain available, but OpenViking memory and file tools are disabled.

To connect local debugging to OpenViking, configure server in the same ov.conf, or set bot.ov_server.server_url explicitly. See Connect to OpenViking.

Scenario C: Use the Gateway as the Unified Entry Point

Use this for long-running deployments, remote access, and multiple chat channels. ovcli.conf.url can point directly to VikingBot Gateway:

ov chat                  → Gateway /bot/v1/chat
ov ls/find/session/...   → Gateway /api/v1/* → OpenViking Server

The Gateway has three OpenViking connection states:

State	Condition	Behavior
Explicit	bot.ov_server.server_url is configured	Connects to the specified OpenViking service; startup fails if it is unreachable
Inherited	No explicit URL, but the same ov.conf contains server	Connects to that OpenViking service; falls back to standalone if it is unreachable
Standalone	No OpenViking service is available	Chat works; OpenViking tools are disabled and /api/v1/* returns 503

1. Configure the Gateway and OpenViking

The following example connects explicitly to a remote OpenViking service:

{
  "bot": {
    "agents": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "api_key": "<your-model-api-key>"
    },
    "gateway": {
      "host": "127.0.0.1",
      "port": 18790
    },
    "ov_server": {
      "server_url": "https://openviking.example.com",
      "api_key": "<bot-openviking-user-api-key>"
    }
  }
}

If the remote OpenViking service uses trusted mode, set api_key_type to "root" and provide the Root Key in api_key.

2. Start the Gateway

vikingbot gateway

The startup log reports the effective state, such as openviking_explicit, openviking_inherited, or standalone_local.

3. Point the ov CLI to the Gateway

Use ov config, or edit ~/.openviking/ovcli.conf:

{
  "url": "http://127.0.0.1:18790",
  "api_key": "<caller-openviking-user-or-admin-api-key>",
  "actor_peer_id": "cli"
}

Chat and other OpenViking commands now use the same entry point:

ov chat -m "Search the project resources and give me a conclusion"
ov ls viking://resources/
ov find "project release process"

4. Configure a Gateway Token for public listeners

By default, the Gateway listens only on 127.0.0.1. If you change the host to 0.0.0.0 or another non-localhost address, you must configure a token or the Gateway will refuse to start:

{
  "bot": {
    "gateway": {
      "host": "0.0.0.0",
      "port": 18790,
      "token": "<strong-random-token>"
    }
  }
}

Add the token to ovcli.conf on the client:

{
  "url": "https://bot.example.com",
  "api_key": "<caller-openviking-user-or-admin-api-key>",
  "gateway_token": "<strong-random-token>",
  "actor_peer_id": "cli"
}

The Gateway Token protects only the Gateway entry point. The OpenViking API Key represents the caller identity. They cannot replace one another, and the Gateway Token is never forwarded to OpenViking.

Connect Chat Platforms

To use Feishu, Slack, Telegram, Discord, WhatsApp, DingTalk, QQ, Email, or MoChat, configure bot.channels on top of Scenario C and start the Gateway.

For example, to configure Feishu:

{
  "bot": {
    "channels": [
      {
        "type": "feishu",
        "enabled": true,
        "app_id": "<feishu-app-id>",
        "app_secret": "<feishu-app-secret>",
        "allow_from": [],
        "ov_tools_enable": true
      }
    ]
  }
}

vikingbot gateway
vikingbot channels status

You can configure multiple instances of the same channel type. VikingBot uses type + channel_id + chat_id to isolate sessions and route replies. See Channel Configuration for credentials, event subscriptions, and permissions for each platform.

Connect to OpenViking

VikingBot and OpenViking share ~/.openviking/ov.conf. Connections are resolved as follows:

1. A managed Bot started by openviking-server --with-bot uses the current Server.
2. A normal vikingbot gateway/chat process first uses an explicit bot.ov_server.server_url.
3. Without an explicit URL, it derives the address from ov.conf.server in the same file.
4. Without an available address, it runs in standalone mode.

Authentication requirements:

OpenViking auth_mode	Bot credential	Gateway request
dev	Local use	The Gateway must listen on localhost
api_key	bot.ov_server.api_key must be a User/Admin Key	The Chat caller must also provide a valid User/Admin Key; Root Keys cannot access data APIs
trusted	Explicit connections use a Root Key; inherited connections may read server.root_api_key	Non-local entry points must also pass the Gateway Token first

The Gateway validates the upstream service and Bot credential at startup, then checks the current OpenViking authentication mode on every request. If the mode changes at runtime, it fails closed and asks you to fix the configuration or restart the Gateway.

VikingBot uses OpenViking to:

• read the current Peer Profile;
• recall events, entities, and preferences by type;
• retrieve Agent Experiences;
• browse, search, and read Resources;
• incrementally synchronize and commit Sessions to extract long-term memories and experiences.

See VikingBot and OpenViking Integration for the complete call flow. The Gateway entry points and authentication boundaries follow RFC #3042.

Configuration

The default configuration file is ~/.openviking/ov.conf. Use an environment variable to select another file:

export OPENVIKING_CONFIG_FILE=/path/to/ov.conf

Restart vikingbot gateway after changing the configuration.

Common Settings

Setting	Default	Description
bot.agents.temperature	0.7	Model sampling temperature
bot.agents.thinking	true	Enable reasoning/thinking when supported by the Provider
bot.agents.timeout	Inherits vlm.timeout	Timeout for one model request
bot.agents.max_tool_iterations	50	Maximum tool iterations in one turn
bot.agents.memory_window	50	Local history window and session commit message threshold
bot.agents.subagent_enabled	true	Whether to expose the spawn tool
bot.gateway.host	127.0.0.1	Gateway listen address
bot.gateway.port	18790	Gateway listen port
bot.sandbox.backend	direct	Execution backend
bot.sandbox.mode	shared	Workspace isolation mode
bot.sandbox.backends.direct.allow_compile_exec	false	Unsafe opt-in that adds exec to Compile when using the direct backend; ordinary Compile tasks still run without it
bot.heartbeat.enabled	true	Whether to check HEARTBEAT.md periodically
bot.heartbeat.interval_seconds	600	Heartbeat interval
bot.mode	normal	One of normal, readonly, or debug

OpenViking Recall Settings

Setting	Default	Description
bot.ov_server.memory_recall_events_limit	10	Event memories recalled per turn
bot.ov_server.memory_recall_entities_limit	10	Entity memories recalled per turn
bot.ov_server.memory_recall_preferences_limit	3	Preference memories recalled per turn
bot.ov_server.memory_recall_max_chars	4000	Character budget for injected Peer Memories
bot.ov_server.exp_recall_limit	5	Number of Experiences recalled
bot.ov_server.exp_recall_max_chars	10000	Character budget for injected Experiences
bot.ov_server.exp_write_tools	write_file,edit_file	Tools that trigger experience recall before writes

Workspace and Agent Customization

The Workspace is VikingBot's local working directory. It contains Agent bootstrap instructions, Skills, Heartbeat tasks, and files used by file and Shell tools. The OpenViking workspace is accessed through openviking_* tools for Resources, Memories, and Skills; it is not the same local directory.

Find the Active Workspace

The Workspace root is derived from storage.workspace:

<storage.workspace>/bot/workspace

When storage.workspace is omitted, the default is ~/.openviking/data/bot/workspace. Check the resolved path with:

vikingbot status

The active directory used by the Agent also depends on bot.sandbox.mode:

Mode	Active Workspace
shared (default)	<workspace>/shared
per-session	<workspace>/<session-key>
per-channel	<workspace>/<channel-key>

For example, with the default configuration, edit ~/.openviking/data/bot/workspace/shared/SOUL.md.

Customize the Agent

When an active Workspace is first used, VikingBot copies initial files from the built-in bot/workspace template. The main customization points are:

File or directory	Purpose	How it is loaded
SOUL.md	Personality, values, and communication style	Added to the system prompt on every turn
AGENTS.md	Global working rules and task constraints; create it when needed	Added to the system prompt on every turn
IDENTITY.md	Agent name, role, and identity background; create it when needed	Added to the system prompt on every turn
TOOLS.md	Tool selection, execution boundaries, and safety rules	Added to the system prompt on every turn
skills/<name>/SKILL.md	Workflows and supporting resources for a class of tasks	A summary is injected first; full instructions are loaded progressively
HEARTBEAT.md	Tasks checked periodically	Read only by Heartbeat

For example, edit SOUL.md in the active Workspace:

# Soul

You are the team's engineering assistant.

- Lead with the conclusion, then add only necessary detail
- Inspect the current state before changing code
- Run relevant verification after making a change
- State assumptions clearly and never invent results

Saved changes normally take effect on the next Agent turn without restarting the Gateway. SOUL.md changes prompt behavior only; it cannot bypass Channel permissions, tool visibility, or Sandbox restrictions.

For the complete loading order, file responsibilities, and customization boundaries, see Agent Capabilities.

Agent Tools

Built-in Tools

Category	Tools
Files and commands	read_file, write_file, edit_file, list_dir, exec
Web	web_search, web_fetch
OpenViking	openviking_list, openviking_search, openviking_grep, openviking_glob, openviking_multi_read, openviking_add_resource, openviking_memory_commit
Other	message, generate_image, cron, spawn

readonly mode does not register openviking_add_resource. When a channel sets ov_tools_enable: false, it does not expose OpenViking tools or inject Profiles, Memories, and Experiences.

MCP Tools

Configure third-party MCP Servers under bot.tools.mcp_servers:

{
  "bot": {
    "tools": {
      "mcp_servers": {
        "filesystem": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
          "tool_timeout": 30,
          "enabled_tools": ["*"]
        },
        "remote": {
          "type": "streamableHttp",
          "url": "https://example.com/mcp",
          "headers": {"Authorization": "Bearer $MCP_TOKEN"},
          "enabled_tools": ["search"]
        }
      }
    }
  }
}

Supported transports are stdio, sse, and streamableHttp. Tool names use the form mcp_<server>_<tool>. A failed MCP connection does not block other Agent capabilities.

Sandbox

Backend	Description
direct	Default; executes directly on the Bot host and is not a strong isolation boundary
srt	Supports file and network allow/deny policies
opensandbox	Connects to OpenSandbox Server
aiosandbox	Connects to an AIO Sandbox service

Workspace modes:

• shared: all sessions share one workspace;
• per-session: every Session has an independent workspace;
• per-channel: sessions on the same channel instance share a workspace.

DirectBackend defaults to restrict_to_workspace: false. For a Gateway exposed to untrusted users, choose an isolated backend and configure channel allowlists and network/file policies.

{
  "bot": {
    "sandbox": {
      "backend": "srt",
      "mode": "per-session"
    }
  }
}

HTTP API

The Gateway Bot API uses the /bot/v1 prefix:

Method	Path	Purpose
POST	/bot/v1/chat	Synchronous chat
POST	/bot/v1/chat/stream	SSE streaming chat
POST	/bot/v1/feedback	Submit response feedback
GET/POST	/bot/v1/sessions	List or create API Sessions
GET/DELETE	/bot/v1/sessions/{id}	Retrieve or delete a Session

When an OpenViking upstream is configured, /api/v1/* is proxied to OpenViking Server.

Operations Commands

Command	Purpose
vikingbot status	Show model and configuration status
vikingbot channels status	Show configured channels
vikingbot channels login	Log in to the WhatsApp bridge
vikingbot cron list	List scheduled jobs
vikingbot cron add	Add a scheduled job
vikingbot cron run	Run a job manually
vikingbot feedback-stats	Aggregate response feedback and outcome metrics

Enable Langfuse with:

{
  "bot": {
    "langfuse": {
      "enabled": true,
      "secret_key": "<langfuse-secret-key>",
      "public_key": "<langfuse-public-key>",
      "base_url": "http://localhost:3000"
    }
  }
}

The repository includes deploy/docker/deploy_langfuse.sh for local deployment.

Security Notes

• Never commit model API Keys, OpenViking API Keys, or Gateway Tokens to the repository.
• A non-localhost Gateway requires a strong random Token and should be protected with HTTPS at the network layer.
• X-Gateway-Token protects only the Gateway; it does not replace an OpenViking user identity.
• allow_from: [] allows every sender. Configure an explicit allowlist for public deployments.
• The direct backend executes files and shell commands with the Bot process user's permissions and is not suitable for untrusted callers.
• openviking_connection may come only from a trusted Server proxy or a trusted local path. Do not accept identity claims directly from a public request body.

More Documentation

• VikingBot Architecture
• Agent Capabilities
• Channels, Gateway, and Operations
• VikingBot and OpenViking Integration
• Channel Configuration