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 .agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ user_invocable: true
# Cut Release Tag

Bump all version strings, open a release PR, and after merge create annotated semver + `latest` tags on `origin/main`.
Do not update `lkg` in this automated release flow; release admins promote `lkg` manually after validation.

This skill delegates the version-bump work to `scripts/bump-version.ts` (invoked via `npm run bump:version`). That script updates package.json (root + plugin), blueprint.yaml, installer defaults, docs config, and versioned doc links — then runs the build and tests before opening a PR.

Expand Down Expand Up @@ -119,6 +120,9 @@ git push origin <new-version>
git push origin latest --force
```

Do not move or push `lkg` in this step.
The public installer defaults to `lkg`, but that tag is the admin-promoted known-good pointer and may intentionally lag `latest`.

## Step 6: Verify

```bash
Expand Down Expand Up @@ -223,4 +227,5 @@ The verification record itself stays in each issue's comment history — only th
- NEVER tag a branch other than `origin/main`.
- Always use annotated tags (`-a`), not lightweight tags.
- The `latest` tag is a floating tag that always points to the most recent release — it requires `--force` to push.
- The `lkg` tag is a manually promoted known-good tag for public installer defaults. Do not update it from the automated release flow.
- The version string passed to `npm run bump:version` should NOT have a `v` prefix (e.g., `0.0.3`, not `v0.0.3`). The script adds the `v` prefix for tags internally.
5 changes: 3 additions & 2 deletions docs/manage-sandboxes/lifecycle.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -179,9 +179,10 @@ Non-interactive re-onboards in the default `suggested` policy mode preserve pres
To make a re-onboard authoritative, set `NEMOCLAW_POLICY_MODE=custom` and provide `NEMOCLAW_POLICY_PRESETS` with the exact list to apply; onboarding removes anything else.
See [`NEMOCLAW_POLICY_MODE`](/reference/commands#nemoclaw-onboard) for the full table.

## Update to the Latest Version
## Update to the Maintained Version

When a new NemoClaw release becomes available, update the `nemoclaw` CLI on your host and check existing sandboxes for stale agent/runtime versions.
When a maintained NemoClaw release becomes available, update the `nemoclaw` CLI on your host and check existing sandboxes for stale agent/runtime versions.
The standard installer follows the admin-promoted `lkg` release tag by default, so it may trail the newest semver or `latest` tag while validation completes.

### Update the NemoClaw CLI

Expand Down
3 changes: 2 additions & 1 deletion docs/reference/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -890,6 +890,7 @@ $ nemoclaw update [--check] [--yes|-y]
| `--yes`, `-y` | Skip the confirmation prompt and run the maintained installer flow |

`nemoclaw update` updates the host-side NemoClaw installation.
The maintained installer flow follows the admin-promoted `lkg` release tag by default, so it may trail the newest semver or `latest` tag while validation completes.
It does not replace `nemoclaw upgrade-sandboxes`; use that command to inspect or rebuild existing sandboxes after the CLI has been updated.
When the command is running from a source checkout, it reports that state and does not replace the checkout with a global package install.

Expand Down Expand Up @@ -1379,7 +1380,7 @@ Set them before running `nemoclaw onboard`.
| `NEMOCLAW_OPENSHELL_BIN` | path | Overrides the `openshell` binary the CLI invokes. Defaults to `openshell` (resolved via `PATH`). |
| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used by `services` and `debug` lookups when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. |
| `NEMOCLAW_INSTALL_REF` | git ref | For internal installer commands: the git ref to install from. Overridden by the `--install-ref` flag. |
| `NEMOCLAW_INSTALL_TAG` | release tag | For internal installer commands: the release tag to install. Overridden by the `--install-tag` flag. |
| `NEMOCLAW_INSTALL_TAG` | release tag | For internal installer commands: the release tag to install. Defaults to the admin-promoted `lkg` tag when unset. Overridden by the `--install-tag` flag. |
| `NEMOCLAW_VLLM_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `qwen3.6-27b`, `nemotron-3-nano-4b`, `deepseek-r1-distill-70b`. Unset uses the per-platform profile default. Gated models (e.g. `deepseek-r1-distill-70b`) require `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`. |
| `NEMOCLAW_MODEL_ROUTER_PYTHON` | absolute path | Pins the host Python interpreter used to create the Model Router virtual environment. Strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to another python. Relative command names such as `python3.12` are rejected. When unset, NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, retains every interpreter whose version is in `[3.10, 3.14)` and whose `ensurepip`, `pyexpat`, `ssl`, and `venv` stdlib modules import cleanly, and tries `python -m venv` on each in priority order until one succeeds. Set the pin when the auto-discovered interpreter is broken (for example, Homebrew `python@3.14` with a `pyexpat` dlopen mismatch on macOS). |

Expand Down
5 changes: 3 additions & 2 deletions install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,14 @@ fi
LOCAL_PAYLOAD="${SCRIPT_DIR:+${SCRIPT_DIR}/scripts/install.sh}"
BOOTSTRAP_TMPDIR=""
PAYLOAD_MARKER="NEMOCLAW_VERSIONED_INSTALLER_PAYLOAD=1"
DEFAULT_INSTALL_REF="lkg"

resolve_release_tag() {
if [[ -n "${NEMOCLAW_INSTALL_REF:-}" ]]; then
printf "%s" "${NEMOCLAW_INSTALL_REF}"
return
fi
printf "%s" "${NEMOCLAW_INSTALL_TAG:-latest}"
printf "%s" "${NEMOCLAW_INSTALL_TAG:-$DEFAULT_INSTALL_REF}"
}

verify_downloaded_script() {
Expand Down Expand Up @@ -113,7 +114,7 @@ bootstrap_usage() {
printf " --help, -h Show this help message and exit\n\n"
printf " Environment:\n"
printf " NEMOCLAW_INSTALL_REF Exact Git ref/SHA to install\n"
printf " NEMOCLAW_INSTALL_TAG Git ref to install (default: latest release)\n"
printf " NEMOCLAW_INSTALL_TAG Git ref to install (default: lkg)\n"
printf " NEMOCLAW_NON_INTERACTIVE=1 Same as --non-interactive\n"
printf " NEMOCLAW_FRESH=1 Same as --fresh\n"
printf " NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 Same as --yes-i-accept-third-party-software\n"
Expand Down
2 changes: 2 additions & 0 deletions scripts/bump-version.ts
Original file line number Diff line number Diff line change
Expand Up @@ -545,6 +545,8 @@ function buildPrBody(previousVersion: string, nextVersion: string, options: PrBo
].join("\n");
}

// Keep automated releases scoped to the semver tag and `latest`.
// The public installer's `lkg` tag is promoted manually by release admins after validation.
function updateLatestTag(tagName: string): void {
log(`Updating mutable 'latest' tag to ${tagName}`);
if (gitRefExists("refs/tags/latest")) {
Expand Down
22 changes: 15 additions & 7 deletions scripts/install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -46,12 +46,20 @@ resolve_repo_root() {
printf "%s\n" "$base"
}
DEFAULT_NEMOCLAW_VERSION="0.1.0"
DEFAULT_INSTALL_REF="lkg"
TOTAL_STEPS=3

is_mutable_install_ref() {
case "${1:-}" in
latest | lkg | refs/tags/latest | refs/tags/lkg) return 0 ;;
*) return 1 ;;
esac
}

resolve_installer_version() {
local repo_root
repo_root="$(resolve_repo_root)"
if [[ -n "${NEMOCLAW_INSTALL_REF:-}" && "${NEMOCLAW_INSTALL_REF}" != "latest" ]]; then
if [[ -n "${NEMOCLAW_INSTALL_REF:-}" ]] && ! is_mutable_install_ref "${NEMOCLAW_INSTALL_REF}"; then
printf "%s" "${NEMOCLAW_INSTALL_REF#v}"
return
fi
Expand Down Expand Up @@ -108,16 +116,16 @@ agent_display_name() {
}

# Resolve which Git ref to install from.
# Priority: NEMOCLAW_INSTALL_TAG env var > "latest" tag.
# Priority: NEMOCLAW_INSTALL_TAG env var > lkg tag.
resolve_release_tag() {
if [[ -n "${NEMOCLAW_INSTALL_REF:-}" ]]; then
printf "%s" "${NEMOCLAW_INSTALL_REF}"
return
fi
# Allow explicit override (for CI, pinning, or testing).
# Otherwise default to the "latest" tag, which we maintain to point at
# the commit we want everybody to install.
printf "%s" "${NEMOCLAW_INSTALL_TAG:-latest}"
# Otherwise default to the "lkg" tag, which we maintain to point at
# the last-known-good commit we want everybody to install.
printf "%s" "${NEMOCLAW_INSTALL_TAG:-$DEFAULT_INSTALL_REF}"
}

clone_nemoclaw_ref() {
Expand Down Expand Up @@ -544,7 +552,7 @@ usage() {
printf " NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1\n"
printf " Continue after manually backing up and retiring old gateway\n"
printf " NEMOCLAW_RECREATE_SANDBOX=1 Recreate an existing sandbox\n"
printf " NEMOCLAW_INSTALL_TAG Git ref to install (default: latest release)\n"
printf " NEMOCLAW_INSTALL_TAG Git ref to install (default: lkg)\n"
printf " NEMOCLAW_PROVIDER build | openai | anthropic | anthropicCompatible\n"
printf " | gemini | ollama | custom | nim-local | vllm | routed\n"
printf " | hermes-provider\n"
Expand Down Expand Up @@ -1405,7 +1413,7 @@ install_nemoclaw() {
info "Installer payload is not a persistent source checkout — installing from GitHub…"
fi
info "Installing ${_CLI_DISPLAY} from GitHub…"
# Resolve the latest release tag so we never install raw main.
# Resolve the maintained install tag so we never install raw main.
local release_ref
release_ref="$(resolve_release_tag)"
info "Resolved install ref: ${release_ref}"
Expand Down
2 changes: 1 addition & 1 deletion src/lib/actions/installer/plan.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ describe("installer plan actions", () => {
it("marks unsupported providers and missing optional probes without failing plan construction", () => {
const plan = buildInstallerPlan({ env: { NEMOCLAW_PROVIDER: "bad-provider" } });

expect(plan.installRef).toBe("latest");
expect(plan.installRef).toBe("lkg");
expect(plan.provider).toMatchObject({ normalized: null, raw: "bad-provider", valid: false });
expect(plan.runtime).toBeNull();
expect(plan.npm).toBeNull();
Expand Down
15 changes: 10 additions & 5 deletions src/lib/actions/update.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import { describe, expect, it, vi } from "vitest";

import {
detectInstallType,
getLatestNemoClawVersionFromGitLatestTag,
getMaintainedNemoClawVersionFromGitTag,
NEMOCLAW_UPDATE_COMMAND,
runUpdateAction,
} from "./update";
Expand Down Expand Up @@ -288,12 +288,12 @@ describe("detectInstallType", () => {
});
});

describe("getLatestNemoClawVersionFromGitLatestTag", () => {
it("resolves the version tag that points at the maintained latest tag", () => {
describe("getMaintainedNemoClawVersionFromGitTag", () => {
it("resolves the version tag that points at the maintained lkg tag", () => {
const spawnSyncImpl = vi.fn(() => ({
status: 0,
stdout: [
"abc123\trefs/tags/latest",
"abc123\trefs/tags/lkg",
"older\trefs/tags/v0.0.36",
"abc123\trefs/tags/v0.0.37",
"future\trefs/tags/v0.1.0",
Expand All @@ -302,6 +302,11 @@ describe("getLatestNemoClawVersionFromGitLatestTag", () => {
signal: null,
}) as never);

expect(getLatestNemoClawVersionFromGitLatestTag({ spawnSyncImpl })).toBe("0.0.37");
expect(getMaintainedNemoClawVersionFromGitTag({ spawnSyncImpl })).toBe("0.0.37");
expect(spawnSyncImpl).toHaveBeenCalledWith(
"git",
expect.arrayContaining(["refs/tags/lkg", "refs/tags/lkg^{}"]),
expect.any(Object),
);
});
});
20 changes: 12 additions & 8 deletions src/lib/actions/update.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import { versionGte } from "../domain/installer/version";
export const NEMOCLAW_INSTALLER_URL = "https://www.nvidia.com/nemoclaw.sh";
export const NEMOCLAW_REPO_URL = "https://github.com/NVIDIA/NemoClaw.git";
export const NEMOCLAW_UPDATE_COMMAND = `curl -fsSL ${NEMOCLAW_INSTALLER_URL} | bash`;
export const NEMOCLAW_MAINTAINED_INSTALL_TAG = "lkg";

type LogFn = (message?: string) => void;
type PromptFn = (question: string) => Promise<string>;
Expand Down Expand Up @@ -105,7 +106,7 @@ export function isSourceCheckout(rootDir: string, env: NodeJS.ProcessEnv = proce
return detectInstallType(rootDir, env) === "source";
}

export function getLatestNemoClawVersionFromGitLatestTag(
export function getMaintainedNemoClawVersionFromGitTag(
deps: {
env?: NodeJS.ProcessEnv;
gitCommand?: string;
Expand All @@ -119,8 +120,8 @@ export function getLatestNemoClawVersionFromGitLatestTag(
"ls-remote",
"--tags",
deps.repoUrl ?? NEMOCLAW_REPO_URL,
"refs/tags/latest",
"refs/tags/latest^{}",
`refs/tags/${NEMOCLAW_MAINTAINED_INSTALL_TAG}`,
`refs/tags/${NEMOCLAW_MAINTAINED_INSTALL_TAG}^{}`,
"refs/tags/v*",
],
{
Expand All @@ -132,18 +133,21 @@ export function getLatestNemoClawVersionFromGitLatestTag(
if (result.error || (result.status ?? 1) !== 0) return null;

const versionsBySha = new Map<string, string>();
let latestSha: string | null = null;
let maintainedSha: string | null = null;
for (const line of trimOutput(result.stdout).split(/\r?\n/)) {
const [sha, ref] = line.trim().split(/\s+/, 2);
if (!sha || !ref) continue;
if (ref === "refs/tags/latest^{}" || (ref === "refs/tags/latest" && !latestSha)) {
latestSha = sha;
if (
ref === `refs/tags/${NEMOCLAW_MAINTAINED_INSTALL_TAG}^{}` ||
(ref === `refs/tags/${NEMOCLAW_MAINTAINED_INSTALL_TAG}` && !maintainedSha)
) {
maintainedSha = sha;
continue;
}
const match = /^refs\/tags\/v(.+?)(\^\{\})?$/.exec(ref);
if (match?.[1]) versionsBySha.set(sha, match[1]);
}
return latestSha ? versionsBySha.get(latestSha) ?? null : null;
return maintainedSha ? versionsBySha.get(maintainedSha) ?? null : null;
}

function updateAvailable(currentVersion: string, latestVersion: string | null): boolean | null {
Expand Down Expand Up @@ -195,7 +199,7 @@ export async function runUpdateAction(
const rootDir = deps.rootDir ?? process.cwd();
const currentVersion = deps.currentVersion();
const branding = updateBranding(env);
const latestVersion = (deps.getLatestVersion ?? (() => getLatestNemoClawVersionFromGitLatestTag({ env })))();
const latestVersion = (deps.getLatestVersion ?? (() => getMaintainedNemoClawVersionFromGitTag({ env })))();
const installType = deps.isSourceCheckout
? deps.isSourceCheckout()
? "source"
Expand Down
6 changes: 3 additions & 3 deletions src/lib/domain/installer/ref.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@

import { describe, expect, it } from "vitest";

import { resolveInstallerVersion, resolveInstallRef } from "./ref";
import { DEFAULT_INSTALL_REF, resolveInstallerVersion, resolveInstallRef } from "./ref";

describe("installer ref helpers", () => {
it("resolves install refs with the same priority as install.sh", () => {
expect(resolveInstallRef({ NEMOCLAW_INSTALL_REF: "feature", NEMOCLAW_INSTALL_TAG: "v1" })).toBe(
"feature",
);
expect(resolveInstallRef({ NEMOCLAW_INSTALL_TAG: "v1" })).toBe("v1");
expect(resolveInstallRef({})).toBe("latest");
expect(resolveInstallRef({})).toBe(DEFAULT_INSTALL_REF);
});

it("derives installer versions from refs and fallback sources", () => {
Expand All @@ -25,7 +25,7 @@ describe("installer ref helpers", () => {
expect(
resolveInstallerVersion({
defaultVersion: "0.1.0",
env: { NEMOCLAW_INSTALL_TAG: "latest" },
env: { NEMOCLAW_INSTALL_TAG: "lkg" },
gitDescribeVersion: "v2.0.0-4-gabc",
packageJsonVersion: "3.0.0",
stampedVersion: "2.0.0",
Expand Down
10 changes: 7 additions & 3 deletions src/lib/domain/installer/ref.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,20 @@ export interface InstallerRefEnv {
NEMOCLAW_INSTALL_TAG?: string | undefined;
}

export const DEFAULT_INSTALL_REF = "lkg";

const MUTABLE_INSTALL_REFS = new Set(["latest", "lkg", "refs/tags/latest", "refs/tags/lkg"]);

export function resolveInstallRef(env: InstallerRefEnv): string {
const explicitRef = env.NEMOCLAW_INSTALL_REF?.trim();
if (explicitRef) return explicitRef;
const tag = env.NEMOCLAW_INSTALL_TAG?.trim();
return tag || "latest";
return tag || DEFAULT_INSTALL_REF;
}

export function installerVersionFromRef(ref: string, fallbackVersion: string): string | null {
const normalized = ref.trim();
if (!normalized || normalized === "latest") return null;
if (!normalized || MUTABLE_INSTALL_REFS.has(normalized)) return null;
return normalized.replace(/^v/, "") || fallbackVersion;
}

Expand All @@ -26,7 +30,7 @@ export function resolveInstallerVersion(input: {
packageJsonVersion?: string | null;
stampedVersion?: string | null;
}): string {
const ref = input.env ? resolveInstallRef(input.env) : "latest";
const ref = input.env ? resolveInstallRef(input.env) : DEFAULT_INSTALL_REF;
const refVersion = installerVersionFromRef(ref, input.defaultVersion);
if (refVersion) return refVersion;

Expand Down
5 changes: 3 additions & 2 deletions test/install-preflight.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2090,7 +2090,7 @@ describe("installer release-tag resolution", () => {
});
}

it("defaults to 'latest' with no env override", () => {
it("defaults to 'lkg' with no env override", () => {
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-resolve-tag-default-"));
const fakeBin = path.join(tmp, "bin");
fs.mkdirSync(fakeBin);
Expand All @@ -2100,7 +2100,7 @@ describe("installer release-tag resolution", () => {
const result = callResolveReleaseTag(fakeBin);

expect(result.status).toBe(0);
expect(result.stdout.trim()).toBe("latest");
expect(result.stdout.trim()).toBe("lkg");
});

it("uses NEMOCLAW_INSTALL_TAG override", () => {
Expand Down Expand Up @@ -2886,6 +2886,7 @@ describe("installer flag parsing", () => {

expect(result.status).toBe(0);
expect(`${result.stdout}${result.stderr}`).toMatch(/NEMOCLAW_INSTALL_TAG/);
expect(`${result.stdout}${result.stderr}`).toMatch(/default: lkg/);
});
});

Expand Down
2 changes: 1 addition & 1 deletion test/internal-cli.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ describe("internal oclif namespace", () => {
expect(JSON.parse(ref.stdout)).toEqual({ installRef: "v2.0.0" });
expect(env.status).toBe(0);
expect(JSON.parse(env.stdout)).toMatchObject({
installRef: "latest",
installRef: "lkg",
provider: { normalized: "nim-local", raw: "nim", valid: true },
});
});
Expand Down
Loading