Skip to content
Merged
Show file tree
Hide file tree
Changes from 5 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
7 changes: 4 additions & 3 deletions docs/reference/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3469,21 +3469,22 @@ Set them before running `$$nemoclaw onboard`.
<AgentOnly variant="openclaw">

Set `NEMOCLAW_SANDBOX_BASE_IMAGE_REF` to an OpenClaw sandbox-base tag or digest to override base-image resolution during onboarding.
Use a release-matched tag or immutable digest for a source-based custom image; NemoClaw resolves the reference and pins a repository digest into a stock-style `ARG BASE_IMAGE` declaration when possible.
Remote overrides must use the official NVIDIA sandbox-base repository and resolve to an immutable repository digest.
Local bases are accepted only when NemoClaw builds and pins them during the current operation; a local image reference supplied through this environment variable is rejected because it has no trusted build capability.

</AgentOnly>

<AgentOnly variant="deepagents">

Set `NEMOCLAW_LANGCHAIN_DEEPAGENTS_CODE_SANDBOX_BASE_IMAGE_REF` to a LangChain Deep Agents Code sandbox-base tag or digest to override base-image resolution during onboarding.
NemoClaw validates the requested image against the manifest-required `deepagents-code` package version before using it.
NemoClaw requires the official remote repository for environment overrides, then validates the requested image against the manifest-required `deepagents-code` package version before using it. Local bases are accepted only when NemoClaw builds and pins them during the current operation.

</AgentOnly>

<AgentOnly variant="hermes">

Set `NEMOCLAW_HERMES_SANDBOX_BASE_IMAGE_REF` to a Hermes sandbox-base tag or digest to override base-image resolution during onboarding.
NemoClaw validates the requested image for the required MCP runtime, and the final Hermes image still accepts only the tracked official digest or a repository-built local base.
NemoClaw requires the official remote repository for environment overrides, validates the requested image for the required MCP runtime, and keeps the final image bound to that trusted base. Local bases are accepted only when NemoClaw builds and pins them during the current operation.

</AgentOnly>

Expand Down
10 changes: 8 additions & 2 deletions src/lib/adapters/docker/image.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,18 @@ import {
dockerRun,
} from "./run";

export type DockerBuildOptions = DockerRunOptions & { quiet?: boolean };
export type DockerBuildOptions = DockerRunOptions & {
labels?: Record<string, string>;
quiet?: boolean;
};

export function dockerBuild(
dockerfilePath: string,
tag: string,
contextDir: string = ROOT,
opts: DockerBuildOptions = {},
): DockerRunResult {
const { quiet, ...rest } = opts;
const { labels, quiet, ...rest } = opts;
// Dockerfile.base relies on `RUN --mount=type=bind`, which is BuildKit-only.
// Hosts whose Docker daemon defaults to the legacy builder (e.g. fresh
// Debian/Ubuntu Docker 29 without /etc/docker/daemon.json) abort the
Expand All @@ -30,6 +33,9 @@ export function dockerBuild(
const args = [
"build",
...(quiet ? ["--quiet"] : []),
...Object.entries(labels ?? {})
.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
.flatMap(([key, value]) => ["--label", `${key}=${value}`]),
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
"-f",
dockerfilePath,
"-t",
Expand Down
24 changes: 24 additions & 0 deletions src/lib/adapters/docker/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,30 @@ describe("docker helpers", () => {
);
});

it("adds sorted image labels to dockerBuild argv and drops them from options", () => {
dockerBuild("Dockerfile.base", "sandbox-base:latest", "/repo/root", {
labels: { "com.example.z": "last", "com.example.a": "first" },
ignoreError: true,
});

expect(runMock).toHaveBeenCalledWith(
[
"docker",
"build",
"--label",
"com.example.a=first",
"--label",
"com.example.z=last",
"-f",
"Dockerfile.base",
"-t",
"sandbox-base:latest",
"/repo/root",
],
{ ignoreError: true, env: { DOCKER_BUILDKIT: "1" } },
);
});

it("forces DOCKER_BUILDKIT=1 on dockerBuild so Dockerfile.base --mount works on legacy-builder hosts (#3583)", () => {
dockerBuild("Dockerfile.base", "sandbox-base:latest", "/repo/root", {
stdio: ["ignore", "inherit", "inherit"],
Expand Down
26 changes: 24 additions & 2 deletions src/lib/agent/base-image.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,10 @@
import { beforeEach, describe, expect, it, vi } from "vitest";

import { makeAgent, withMockedDocker } from "../../../test/helpers/base-image-test-harness";
import type { SandboxBaseImageResolutionMetadata } from "../sandbox-base-image";
import {
createSandboxBaseImageBuildProvenanceKey,
type SandboxBaseImageResolutionMetadata,
} from "../sandbox-base-image";

function makeResolutionMetadata(
overrides: Partial<SandboxBaseImageResolutionMetadata> = {},
Expand Down Expand Up @@ -147,6 +150,16 @@ describe("agent base image provisioning", () => {
);

const result = ensureAgentBaseImage(makeAgent(), { forceBaseImageRebuild: true });
const buildOptions = dockerBuildMock.mock.calls[0]?.[3] as {
labels?: Record<string, string>;
};
const provenance = buildOptions.labels?.["com.nvidia.nemoclaw.base-build-provenance"];
const expectedProvenanceKey = createSandboxBaseImageBuildProvenanceKey({
imageName: "ghcr.io/nvidia/nemoclaw/hermes-sandbox-base",
dockerfilePath: "/test/root/agents/hermes/Dockerfile.base",
localTag: "unused-by-build-provenance",
rootDir: root,
});

expect(result.imageTag).toBe(`nemoclaw-hermes-sandbox-base-local:image-${"a".repeat(64)}`);
expect(result.built).toBe(true);
Expand All @@ -166,14 +179,23 @@ describe("agent base image provisioning", () => {
}),
validateImage: expect.any(Function),
validationDescription: "the required MCP Streamable HTTP runtime",
trustedLocalOverride: { ref: result.imageTag, provenance },
}),
);
expect(dockerImageInspectMock).not.toHaveBeenCalled();
expect(dockerBuildMock).toHaveBeenCalledWith(
"/test/root/agents/hermes/Dockerfile.base",
expect.stringMatching(/^nemoclaw-hermes-sandbox-base-local:build-\d+-[0-9a-f]{16}$/),
root,
{ ignoreError: true, stdio: ["ignore", "inherit", "inherit"] },
{
ignoreError: true,
labels: {
"com.nvidia.nemoclaw.base-build-provenance": expect.stringMatching(
new RegExp(`^${expectedProvenanceKey}\\.[0-9a-f]{64}$`),
),
},
stdio: ["ignore", "inherit", "inherit"],
},
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
);
expect(dockerImageInspectFormatMock).toHaveBeenCalledWith(
"{{.Id}}",
Expand Down
29 changes: 27 additions & 2 deletions src/lib/agent/base-image.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,18 @@ import { ROOT } from "../runner";
import { SANDBOX_BUILD_CONTEXT_PREFIX } from "../sandbox/build-context";
import {
buildLocalBaseTag,
createSandboxBaseImageBuildProvenance,
createSandboxBaseImageResolutionKey,
createSandboxBaseImageResolutionMetadata,
getImageGlibcVersion,
type ResolveBaseImageOptions,
resolveSandboxBaseImage,
SandboxBaseImageResolutionError,
SANDBOX_BASE_BUILD_PROVENANCE_LABEL,
SANDBOX_BASE_TAG,
type SandboxBaseImageResolution,
type SandboxBaseImageResolutionMetadata,
type TrustedLocalBaseImageOverride,
} from "../sandbox-base-image";
import { createDeepAgentsCodeBaseImageResolutionOptions } from "./deep-agents-code-base-image";
import type { AgentDefinition } from "./defs";
Expand Down Expand Up @@ -211,6 +214,17 @@ function createLocalResolutionMetadata(
);
}

function localBaseImageBuildProvenance(options: ResolveBaseImageOptions): {
labels: Record<string, string>;
provenance: string;
} {
const provenance = createSandboxBaseImageBuildProvenance(options);
return {
labels: { [SANDBOX_BASE_BUILD_PROVENANCE_LABEL]: provenance },
provenance,
};
}

/**
* Ensure the agent-specific sandbox base image exists locally.
* Rebuild callers can force this so local Dockerfile.base edits are applied.
Expand All @@ -229,7 +243,10 @@ export function ensureAgentBaseImage(
const baseImageName = resolutionOptions.imageName;
const baseImageTag = `${baseImageName}:${SANDBOX_BASE_TAG}`;
const overrideEnvVar = getAgentSandboxBaseImageEnvVar(agent.name);
const resolveExactImage = (imageRef: string) =>
const resolveExactImage = (
imageRef: string,
trustedLocalOverride?: TrustedLocalBaseImageOverride,
) =>
resolveSandboxBaseImage({
...resolutionOptions,
localTag: imageRef,
Expand All @@ -238,13 +255,16 @@ export function ensureAgentBaseImage(
[overrideEnvVar]: imageRef,
NEMOCLAW_SANDBOX_BASE_LOCAL_BUILD: "0",
},
trustedLocalOverride,
});

if (options.forceBaseImageRebuild === true) {
const forceBuildTag = `nemoclaw-${agent.name}-sandbox-base-local:build-${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
const buildProvenance = localBaseImageBuildProvenance(resolutionOptions);
console.log(` Rebuilding ${agent.displayName} base image...`);
const buildResult = dockerBuild(baseDockerfile, forceBuildTag, ROOT, {
ignoreError: true,
labels: buildProvenance.labels,
stdio: ["ignore", "inherit", "inherit"],
});
if (buildResult.error || buildResult.status !== 0) {
Expand All @@ -258,7 +278,10 @@ export function ensureAgentBaseImage(
const pinnedBaseImageTag = pinAgentSandboxBaseImageRef(agent.name, forceBuildTag);
let resolved: SandboxBaseImageResolution | null = null;
try {
resolved = resolveExactImage(pinnedBaseImageTag);
resolved = resolveExactImage(pinnedBaseImageTag, {
ref: pinnedBaseImageTag,
provenance: buildProvenance.provenance,
});
} catch (error) {
if (!(error instanceof SandboxBaseImageResolutionError)) throw error;
}
Expand Down Expand Up @@ -317,8 +340,10 @@ export function ensureAgentBaseImage(
});
if (inspectResult?.status !== 0) {
console.log(` Building ${agent.displayName} base image (first time only)...`);
const buildProvenance = localBaseImageBuildProvenance(resolutionOptions);
const buildResult = dockerBuild(baseDockerfile, baseImageTag, ROOT, {
ignoreError: true,
labels: buildProvenance.labels,
stdio: ["ignore", "inherit", "inherit"],
});
if (buildResult.error || buildResult.status !== 0) {
Expand Down
Loading
Loading