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

OpenViking Server requirement: VikingBot addresses the caller's own context space through the viking://~ home alias (for example viking://~/memories/), so it requires a server with viking://~ support. The uid-less shorthand viking://user/memories is no longer emitted and is rejected by newer servers.

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. bot.ov_server.server_url is ignored, while an explicit bot.ov_server.api_key and other Bot OpenViking settings are preserved. In api_key mode, that key must be a User/Admin key. 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:

A managed Bot started by openviking-server --with-bot uses the current Server.
A normal vikingbot gateway/chat process first uses an explicit bot.ov_server.server_url.
Without an explicit URL, it derives the address from ov.conf.server in the same file.
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.agents.subagent_max_concurrency`	`4`	Maximum number of background subagents running at once
`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`	`true`	Set to `false` to disable
`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.

Note

Edit files in the active Workspace. bot/workspace in the repository or installed package is an initialization template and does not overwrite an existing Workspace. Never store API Keys or other secrets in bootstrap files.

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.

README.md

VikingBot