Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

## Unreleased

- Added `beta` and `extended-stable` channel resolution, including support for the npm `extended-stable` dist-tag.
- Resolved channel names to concrete versions before install so defaults, pins, and `ocvm list` stay reproducible.
- Added Node.js runtime checks to install and `doctor` for OpenClaw's current Node 24/26/27 requirements, including prerelease rejection for Node 24/26.
- Fixed local and remote version ordering for OpenClaw's unpadded calendar versions.
- Updated the Docker e2e image to Node 26 and refreshed channel documentation.
- Replaced GitHub raw installer guidance with a static installer path that can be mirrored to OSS/CDN.
- Added website documentation routes for installation, commands, configuration, and release sources.
- Added GitHub and documentation navigation to the landing page.
Expand Down
24 changes: 21 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,29 @@ This is a version manager, not an OpenClaw installer replacement. Installation i

Website: https://ocvm.vercel.app

## Requirements

OpenClaw currently requires Node.js 24.16+ on the 24.x line, 26.1+ on the
26.x line, or 27+ (24.22.1+ / 26.12.1+ recommended). Node 24/26 prereleases
and Node 22, 23, and 25 are unsupported. `ocvm` does not install or switch
Node.js; `ocvm doctor` reports unsupported runtimes before they turn into
confusing install failures.

## Status

MVP crate scaffold with the full command surface from the PRD:

```bash
ocvm install <version|latest|stable>
ocvm install <version|latest|stable|beta|extended-stable>
ocvm uninstall <version>
ocvm use <version>
ocvm default <version>
ocvm current
ocvm list
ocvm list-remote
ocvm list-remote --channel stable
ocvm list-remote --channel nightly
ocvm list-remote --channel beta
ocvm list-remote --channel extended-stable
ocvm pin <version>
ocvm unpin
ocvm init <zsh|bash|fish>
Expand Down Expand Up @@ -130,7 +139,11 @@ Manifest format:

The release provider also accepts a raw array of version objects. Tarball fields can be named `url`, `tarball`, or `npm`.

The npm provider maps `stable` to the `latest` dist-tag when npm does not define a separate `stable` dist-tag. Project config can override this with `channels.stable`.
The npm provider resolves `latest`, `stable` (npm's `latest` tag), `beta`, and
`extended-stable` to a concrete version before installing. `beta` falls back to
`latest` when npm has no beta tag; `extended-stable` never falls back. Project
config can override any channel with `channels.<name>`. Release manifests opt
into the same behavior through their `tags` arrays.

Release manifest entries can include `sha256` or `executableSha256`. When present, `ocvm` verifies the staged `openclaw` executable before activation.

Expand Down Expand Up @@ -196,6 +209,11 @@ ocvm rollback before-upgrade

Rollback does not delete unrelated installed versions.

`snapshot` and `rollback` only restore ocvm's default and session selection.
They do not back up OpenClaw's configuration or SQLite state. OpenClaw refuses
to open state written by a newer schema, so use OpenClaw's own backup tooling
(see `openclaw backup --help`) before switching to an older release.

## Install

After a GitHub Release exists, publish `install.sh` to a stable HTTPS path. The
Expand Down
5 changes: 3 additions & 2 deletions site/src/content.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,13 @@ export const commandGroups = [
{
title: 'Install and remove',
commands: [
'ocvm install <version|latest|stable>',
'ocvm install <version|latest|stable|beta|extended-stable>',
'ocvm uninstall <version>',
'ocvm list',
'ocvm list-remote',
'ocvm list-remote --channel stable',
'ocvm list-remote --channel nightly',
'ocvm list-remote --channel beta',
'ocvm list-remote --channel extended-stable',
],
},
{
Expand Down
7 changes: 7 additions & 0 deletions site/src/routes/docs.installation.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,13 @@ function InstallationDocs() {
<pre>
<code>{installCommand}</code>
</pre>
<h2>Node.js requirement</h2>
<p>
ocvm installs OpenClaw but does not install Node.js. OpenClaw currently
requires Node.js 24.16+ on 24.x, 26.1+ on 26.x, or 27+ (24.22.1+ /
26.12.1+ recommended). Run <code>ocvm doctor</code> to check the
active runtime.
</p>
<h2>Release layout</h2>
<p>Publish one stable installer script:</p>
<pre>
Expand Down
6 changes: 3 additions & 3 deletions site/src/routes/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,16 @@ const features = [
body: 'Commit .openclaw-version and every shell in the repo resolves the same OpenClaw version before falling back to user defaults.',
},
{
title: 'Stable and exact installs',
body: 'Install stable, latest, nightly, or an exact version from npm today, with release manifests ready for GitHub Release assets.',
title: 'Release channels and exact installs',
body: 'Install stable, extended-stable, beta, latest, or an exact version from npm, with release manifests ready for GitHub Release assets.',
},
{
title: 'Snapshot and rollback',
body: 'Capture current default and session metadata before upgrades, then rollback that state without deleting installed versions.',
},
{
title: 'Doctor checks',
body: 'Inspect PATH, shims, defaults, project pins, and installed executables when a local OpenClaw environment behaves strangely.',
body: 'Inspect Node.js, PATH, shims, defaults, project pins, and installed executables when a local OpenClaw environment behaves strangely.',
},
{
title: 'Release verification',
Expand Down
15 changes: 8 additions & 7 deletions src/cli.rs
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
use crate::config;
use crate::paths::OcvmPaths;
use crate::project;
use crate::source::provider_from_config;
use crate::source::{is_channel_name, provider_from_config};
use crate::version;
use anyhow::{anyhow, Result};
use clap::{Parser, Subcommand, ValueEnum};
Expand All @@ -16,7 +16,7 @@ pub struct Cli {

#[derive(Debug, Subcommand)]
enum Commands {
/// Install an OpenClaw version, latest, or stable.
/// Install an OpenClaw version or a release channel (latest, stable, beta, extended-stable).
Install { version: String },
/// Uninstall an installed OpenClaw version.
Uninstall { version: String },
Expand Down Expand Up @@ -120,7 +120,9 @@ where
}
Commands::ListRemote { channel } => {
let source = provider_from_config(&paths)?;
for remote in source.list_remote(channel.as_deref())? {
let mut remotes = source.list_remote(channel.as_deref())?;
remotes.sort_by(|left, right| version::compare_versions(&left.version, &right.version));
for remote in remotes {
if remote.tags.is_empty() {
println!("{}", remote.version);
} else {
Expand Down Expand Up @@ -201,14 +203,13 @@ end
}

fn resolve_for_local_command(paths: &OcvmPaths, requested: &str) -> Result<String> {
if requested != "latest" && requested != "stable" {
return Ok(requested.to_string());
}

let config = config::load(paths)?;
if let Some(version) = config.channels.get(requested) {
return Ok(version.clone());
}
if !is_channel_name(requested) {
return Ok(requested.to_string());
}

let source = provider_from_config(paths)?;
source.resolve_alias(requested)
Expand Down
43 changes: 33 additions & 10 deletions src/source.rs
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,12 @@ pub trait SourceProvider {
}
}

pub const CHANNEL_NAMES: [&str; 4] = ["latest", "stable", "beta", "extended-stable"];

pub fn is_channel_name(value: &str) -> bool {
CHANNEL_NAMES.contains(&value)
}

pub struct NpmSource {
package: String,
}
Expand Down Expand Up @@ -55,15 +61,21 @@ impl NpmSource {

impl SourceProvider for NpmSource {
fn resolve_alias(&self, requested: &str) -> Result<String> {
if requested != "latest" && requested != "stable" {
if !is_channel_name(requested) {
return Ok(requested.to_string());
}
let tags = self.npm_json(&["view", &self.package, "dist-tags", "--json"])?;
tags.get(requested)
.or_else(|| tags.get("latest"))
let resolved = match requested {
"stable" => tags.get("stable").or_else(|| tags.get("latest")),
"beta" => tags.get("beta").or_else(|| tags.get("latest")),
"latest" => tags.get("latest"),
"extended-stable" => tags.get("extended-stable"),
_ => None,
};
resolved
.and_then(|value| value.as_str())
.map(ToOwned::to_owned)
.ok_or_else(|| anyhow!("npm dist-tags did not include {requested} or latest"))
.ok_or_else(|| anyhow!("npm dist-tags did not include {requested}"))
}

fn list_remote(&self, channel: Option<&str>) -> Result<Vec<RemoteVersion>> {
Expand All @@ -79,7 +91,7 @@ impl SourceProvider for NpmSource {
.as_str()
.ok_or_else(|| anyhow!("npm versions response included a non-string version"))?;
let mut labels = Vec::new();
for tag in ["stable", "latest", "beta"] {
for tag in ["stable", "latest", "beta", "extended-stable"] {
if tags.get(tag).and_then(|value| value.as_str()) == Some(version) {
labels.push(tag.to_string());
}
Expand Down Expand Up @@ -166,14 +178,25 @@ impl ReleaseSource {

impl SourceProvider for ReleaseSource {
fn resolve_alias(&self, requested: &str) -> Result<String> {
if requested != "latest" && requested != "stable" {
if !is_channel_name(requested) {
return Ok(requested.to_string());
}
self.versions()?
.into_iter()
let versions = self.versions()?;
if let Some(version) = versions
.iter()
.find(|version| version.tags.iter().any(|tag| tag == requested))
.map(|version| version.version)
.ok_or_else(|| anyhow!("release manifest did not include {requested}"))
{
return Ok(version.version.clone());
}
if requested == "stable" || requested == "beta" {
if let Some(version) = versions
.iter()
.find(|version| version.tags.iter().any(|tag| tag == "latest"))
{
return Ok(version.version.clone());
}
}
Err(anyhow!("release manifest did not include {requested}"))
}

fn list_remote(&self, channel: Option<&str>) -> Result<Vec<RemoteVersion>> {
Expand Down
Loading
Loading