Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
OpenViking Release Guide
This document explains the release goals, version and tag conventions, primary release flows, republishing paths, and verification steps for the OpenViking repository. It is based on the tracked GitHub Actions workflows, build configuration, and package configuration in this repository.
Release Goals
OpenViking does not release a single artifact. A release publishes a set of related assets for different usage paths:
openvikingPython package: for users who need the local runtime, server, CLI, and full feature set.- Python SDK
openviking-sdk: for lightweight HTTP clients that call an existing OpenViking server. - Microsoft Agent Framework adapter
openviking-ms-agent-framework: for MAF applications using an existing OpenViking server. - Docker images: for containerized deployments, published to GHCR and Docker Hub.
- TOS release assets: for source archives, installation scripts, and stable download paths.
- Rust CLI / npm packages: for users who install the
ovCLI through npm. - OpenClaw / ClawHub plugin: for OpenClaw plugin distribution.
- TypeScript SDK
@openviking/sdk: for TypeScript and JavaScript HTTP clients. - OpenCode plugin
@openviking/opencode-plugin: for OpenCode integration distribution. - Controlplane MCP
mcp-server-openviking-controlplane: MCP server andov-cpCLI for the control plane. - VikingBot: currently distributed through
openviking[bot]and the official Docker image; historical standalone release entries are documented separately to avoid misuse.
A formal main-package release should keep the Python package, Docker images, and TOS assets on the same main release tag. SDK, CLI, and ClawHub plugin releases use their own tag or version namespaces.
Version and Tag Conventions
Use the following tag conventions:
| Artifact | Recommended tag / version | Notes |
|---|---|---|
openviking main package |
vX.Y.Z |
Main release tag, for example v0.3.26. |
openviking-sdk |
[email protected] |
SDK-only tag, for example [email protected]. |
openviking-ms-agent-framework |
[email protected] |
Must match the version in integrations/frameworks/microsoft-agent-framework/pyproject.toml. |
@openviking/sdk (TypeScript) |
[email protected] |
TypeScript SDK tag. |
| Rust CLI / npm CLI | [email protected] |
CLI-only tag, for example [email protected]. |
Vika (vika/) |
[email protected] |
Must match the version in vika/package.json. See Vika Release Flow. |
| ClawHub plugin latest | YYYY.M.D or YYYY.M.D-N |
Generated by the workflow or specified manually. |
| ClawHub plugin dev | YYYY.M.D-dev.N |
Used for the dev channel. |
The main package version is resolved from Git tags through setuptools_scm; formal main releases should use vX.Y.Z. The SDK also uses setuptools_scm, but it only matches python-sdk@* tags so it does not conflict with main package tags.
Formal Main Package Release Flow
Formal main package releases go through GitHub Releases in the root repository:
- Confirm the release changes are merged into the target branch and PR / main branch checks have passed.
- Create a main package tag, for example
v0.3.26. - Publish a GitHub Release based on that tag.
- The
03. Releaseworkflow runs when the Release is published. - The workflow reuses
_Build Distributionto build the sdist and multi-platform wheels. - The workflow publishes the distributions to PyPI.
- The workflow builds and pushes multi-architecture Docker images.
- The
20. Release TOS Uploadworkflow uploads the source archive and installation scripts to TOS.
A formal main release publishes to:
- PyPI:
openviking - GHCR:
ghcr.io/<owner>/<repo> - Docker Hub:
<dockerhub-user>/openviking - TOS: versioned release paths and optional
lateststable paths
Manual Main Package Builds, Test Publishing, and Republishing
The root release workflow also supports manual dispatch with these targets:
none: build only, without publishing.testpypi: publish to TestPyPI.pypi: publish to PyPI.both: publish to both TestPyPI and PyPI.
If Python distributions were built successfully but publishing failed, use the _Publish Distribution workflow with the relevant build run id. This path is intended for recovery and republishing, not as the normal release entry point.
Docker Image Publishing and Republishing
During a formal main release, Docker images are built and published by the main release workflow. Images are pushed to GHCR and Docker Hub with the release version tag and latest tag.
The repository also provides a standalone Build and Push Docker Image workflow for:
- Rebuilding an image with a manually specified version.
- Building images from the
mainbranch. - Rebuilding or republishing images after a tag-triggered run.
Note: the standalone Docker workflow currently also runs on v*.*.* tag pushes. The formal GitHub Release source of truth is still the 03. Release workflow; treat the standalone Docker workflow as an image-specific build or republish path to avoid confusing it with the formal release artifact set.
To avoid duplicate publishing, use the main release workflow for formal versions. Use the standalone Docker workflow only for image republishing or special verification.
TOS Release Assets
The TOS release flow creates a source archive and uploads these assets:
releases/<tag>/openviking-<tag>-source.zip- Claude Code memory plugin install script
- Codex memory plugin install script
- Matching TOS install scripts
Formal GitHub Releases trigger the TOS upload automatically and overwrite the stable paths. A manual run takes a tag and uploads its versioned paths; it overwrites the stable paths only with update_latest=true (default false), so repairing an older release's assets does not move users back to that release.
If TOS secrets are not fully configured, the workflow skips uploading and reports it in the step summary without failing the whole workflow.
Memory Plugin Downloads on the Docs Site
The installer and the memory plugins are downloaded from the documentation site, not from the TOS release bucket. Both docs deployments (17. Docs to GitHub Pages at docs.openviking.ai, 19. Docs TOS Deploy to docs.openviking.net) run .github/scripts/build-plugin-downloads.sh and publish its output under /dl, with the same layout as the release bucket: memory-plugin-shared/install.sh and bootstrap.sh, releases/latest/memory-plugin-marketplace.zip, plugins/claude/marketplace.json with plugins/claude/openviking-memory-<plugin version>.zip, plugins/memory-plugins.git, and releases/latest/channels.json, which the install site's version check reads.
They deploy on every push to main that changes the docs, a plugin, the installer or .github/scripts, so a plugin change is published when it is merged, without a tag or a GitHub Release. The published installer reports <date>-<commit> as its version. To publish a plugin fix, merge it with the version bumps that .github/scripts/check-plugin-version-bumps.sh requires; to roll back, revert the change on main and bump the versions again. Both workflows can also be started by hand from main.
The TOS release bucket keeps receiving the same files with each release for installs that still point at it, as described below.
Memory Plugin Hotfix and Rollback on TOS
Installs that point at the TOS release bucket read its stable paths: plugins/claude/marketplace.json (Claude Code), plugins/memory-plugins.git (Codex and TraeCode CLI), releases/latest/memory-plugin-marketplace.zip (every other host), releases/latest/channels.json (install version resolution), and memory-plugin-shared/install.sh and bootstrap.sh. One run of the workflow builds all of them from the commit of the tag it is given.
To publish a plugin hotfix there without a product release:
- Merge the fix with the plugin version bumps that
.github/scripts/check-plugin-version-bumps.shrequires. Claude Code only updates an installed plugin when its version string changes. - Tag a commit that holds the last release plus the fix, for example on a branch cut from the last
vX.Y.Ztag with the fix cherry-picked. Use a tag that does not start withv, such asmemory-plugins-YYYY.M.D, and do not publish a GitHub Release for it:v*.*.*tag pushes trigger the Docker workflow, published Releases trigger the main release workflows, and the main package version is resolved fromv*tags. - Push the tag and run
gh workflow run release-tos.yml -f tag=<tag> -f update_latest=true.
To roll back, run gh workflow run release-tos.yml -f tag=<last good tag> -f update_latest=true. The workflow definition comes from the default branch, but the scripts it calls come from the tag's checkout, so only tags that already contain the current release scripts can be republished; to go back further, publish the older plugin code as a hotfix.
After either run, Claude Code (URL marketplace) picks up the change at its next update check, and a lower version counts as an update. Codex picks it up at its next start, TraeCode CLI on trae-cli plugin marketplace upgrade. Cursor, TRAE, TRAE CN, ZCode, Kimi Code, OpenCode, pi, and Claude Code installs on a local directory marketplace change only when the installer is re-run. dsh installs from npm and is not affected.
Python SDK Release Flow
The Python SDK lives under sdk/python, and its PyPI package name is openviking-sdk. SDK releases use an independent tag namespace:
[email protected]
Typical flow:
- Merge SDK-related changes.
- Create and push a tag, for example
[email protected]. - The
Python SDK Releaseworkflow runs from the tag. - The workflow resolves the SDK version with
setuptools_scm. - The workflow verifies that the current tag equals
python-sdk@<resolved-version>. - The workflow builds
sdk/pythonand publishes it to PyPI.
The SDK workflow also supports manual dispatch with testpypi, pypi, or both. Manual dispatch is useful for validation and recovery; formal SDK releases should use [email protected] tags.
Microsoft Agent Framework Release Flow
The adapter lives under integrations/frameworks/microsoft-agent-framework and has an independent version in its pyproject.toml.
- Merge the package changes and confirm the integration checks pass.
- Run
Microsoft Agent Framework Integration Releasemanually with targettestpypi, then verify the published wheel installs and imports. - Create an
[email protected]tag on the tested commit and publish a GitHub Release for that tag, with latest disabled (gh release create <tag> --latest=false). The workflow checks that the tag matches the package version, runs the offline contracts, builds the distributions, and publishes to PyPI.
Manual dispatch also supports pypi and both for publishing and recovery. A tag push alone does not start this workflow.
Configure GitHub Trusted Publishers separately on PyPI and TestPyPI for repository volcengine/OpenViking, workflow filename python-agent-framework-release.yml, and environments pypi and testpypi respectively. For the first release, register pending publishers under the package name openviking-ms-agent-framework. Publishing authenticates with OIDC.
Rust CLI / npm Release Flow
The Rust CLI tag format is:
[email protected]
After a cli@* tag is pushed, the Rust CLI Build workflow builds the ov binary for multiple platforms and publishes npm packages:
- Platform packages:
@openviking/cli-linux-x64,@openviking/cli-linux-arm64,@openviking/cli-darwin-x64,@openviking/cli-darwin-arm64,@openviking/cli-win32-x64 - Wrapper package:
@openviking/cli
The workflow injects the version from the tag into the platform packages and wrapper package. If the same version already exists on npm, the workflow skips the already published package.
Vika Release Flow
Vika (vika/) ships as one self-contained archive per platform: linux-x64, linux-arm64, darwin-x64 and darwin-arm64, each with its own Node and dependencies. The Vika Release workflow (vika-release.yml) tests, builds and uploads them to the TOS release bucket under vika/:
vika/releases/<version>/: the archives with their.sha256files,install.sh, andrelease.json, which is uploaded last. A version is published once: a run stops when a different build of it is uploaded already, while re-running a failed publish job finishes the same build. Publish jobs run one at a time.vika/install.shandvika/latest: written last, and only by a formal release newer than the currentvika/latest. Users install withcurl -fsSL https://ovrelease.tos-cn-beijing.volces.com/vika/install.sh | sh, andvika upgradefollowsvika/latest. A tag with an older version, such as a hotfix on an earlier line, or with a-in it, such as[email protected], publishes only its own directory; a-version's GitHub Release is marked as a pre-release.
Formal release: set the version in vika/package.json, merge, then push the matching [email protected] tag. The tag must not start with v: v*.*.* tag pushes and Releases of v* tags run the main package workflows. The workflow also creates a GitHub Release for the tag that is not marked as the repository's latest release.
Preview of a branch: run the workflow on that branch, from the Actions page or with gh workflow run vika-release.yml --ref <branch>. It publishes <package version>-<commit> without moving vika/latest, and the run summary shows the install command. Only branches in this repository can be previewed, because publishing needs the TOS secrets.
Pull requests that touch vika/ run the tests and build and check the linux-x64 archive without publishing.
The workflow uses the same TOS secrets as release-tos.yml. The VIKA_DOWNLOAD_BASE and VIKA_TOS_PREFIX repository variables override the public address and the key prefix, for example to rehearse in a fork against a test bucket.
OpenClaw / ClawHub Plugin Release
The OpenClaw plugin is published manually through the OpenViking OpenClaw plugin release workflow. Inputs include:
version: optional; when empty, the workflow generates a date-based version.channel:auto,dev, orlatest.changelog: release notes for the plugin release.
The workflow resolves the channel and version, packs examples/openclaw-plugin, pushes a generated package branch, and then calls ClawHub's official trusted publishing workflow.
Recommended usage:
- Use
latestorautofor the formal channel. - Use
devfor development validation. - When specifying
versionmanually, ensure it matches the required format for the selected channel.
Other Release Flows
- TypeScript SDK Release (
typescript-sdk-release.yml): triggered by pushing a[email protected]tag, or manually. Publishes@openviking/sdkto npm. - Plugin npm Release (
plugin-npm-release.yml): runs automatically on pushes tomainthat touchexamples/dsh-memory-plugin/**,examples/opencode-plugin/**, or the shared plugin libraryexamples/memory-plugin-shared/lib/**, or manually. Publishes@openviking/dsh-memory-pluginand@openviking/opencode-pluginto npm, one matrix job per package, and skips versions that already exist. - Controlplane MCP Release (
controlplane-mcp-release.yml): manual only. Publishesmcp-server-openviking-controlplane, including theov-cpCLI.
VikingBot Release Notes
VikingBot is no longer maintained as a recommended standalone PyPI release path. The current distribution model is through the main package:
- Python install entry point:
pip install "openviking[bot]". - Source development entry point:
uv pip install -e ".[bot]". - The official Docker image already includes VikingBot by default; disable it with
--without-botorOPENVIKING_WITH_BOT=0.
The former root-level First Release to PyPI workflow has been removed. The current bot/ directory does not contain an independent pyproject.toml, setup.py, or setup.cfg, so it cannot be released as a standalone Python package from this repository.
The file bot/.github/workflows/release.yml lives under the bot subdirectory. Treat it as a historical bot subproject or split-repository release reference, not as a GitHub Actions workflow that the current root repository can directly trigger. Restoring an independent vikingbot package would first require adding standalone Python package metadata, a versioning strategy, and a publishing credential strategy under bot/.
Pre-release Checklist
Before releasing, confirm that:
- The changes to be released are merged into the target branch.
- CI / PR checks have passed.
- The version has not already been published to PyPI, npm, or the Docker registry.
- The tag name follows the convention for the target artifact.
- Python dependencies, build configuration, and README files are synchronized.
- Required secrets or trusted publishing settings are configured for Docker Hub, PyPI/TestPyPI, TOS, npm, and ClawHub.
- Release notes are ready and document breaking changes, migration steps, and important fixes.
Post-release Verification Checklist
After releasing, verify that:
- The package version on PyPI / TestPyPI matches the tag.
pip install openviking==<version>orpip install openviking-sdk==<version>succeeds.- Docker registries contain the version tag and the expected
latest/maintag. - The multi-architecture Docker manifest can be pulled.
- TOS versioned paths and stable paths are accessible.
- npm contains the expected CLI platform packages and wrapper package.
- The ClawHub plugin channel and version match expectations.
Failure Handling and Republishing Principles
- PyPI and npm versions generally cannot be overwritten; if package content is wrong, publish a new version.
- Docker
latest,main, and manually specified tags can be rebuilt through the image republishing workflow, but keep released version tags traceable. - Treat TOS versioned paths as immutable assets; stable paths may be overwritten through the manual workflow.
- If build succeeds but publishing fails, prefer the republishing workflow or manual dispatch instead of recreating the same tag with different content.
- If a tag is wrong, delete and recreate it only if it has not triggered irreversible publishing.