Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 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
3 changes: 0 additions & 3 deletions .github/workflows/e2e.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2781,9 +2781,6 @@ jobs:
npx vitest run --project e2e-live \
test/e2e/live/full-e2e.test.ts \
--silent=false --reporter=default
npx vitest run --project e2e-live \
test/e2e/live/onboard-progress-budget.test.ts \
--silent=false --reporter=default

- name: Upload full-e2e artifacts
if: always()
Expand Down
2 changes: 2 additions & 0 deletions docs/deployment/install-openclaw-plugins.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,8 @@ To run a second sandbox alongside an existing one, use a dedicated build directo
## Build Performance

Custom plugin images are normal Docker builds, so build time depends on the build context size and the Docker layer cache rather than on NemoClaw.
NemoClaw sends user-supplied `--from` contexts to the OpenShell gateway builder and reserves its host-side local BuildKit prebuild for contexts that NemoClaw generates itself.
On a local Docker-driver gateway, a `Local BuildKit build skipped` notice is expected and the custom image build continues through the gateway.

Keep the build context small and dedicated.
The Dockerfile's parent directory is staged as the build context before the Docker build starts, so a broad directory can make onboarding look stuck while Docker is only preparing context.
Expand Down
2 changes: 2 additions & 0 deletions docs/manage-sandboxes/install-plugins-hermes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,8 @@ Put the custom Dockerfile and every file it needs to `COPY` in one directory.
`nemohermes onboard --from <Dockerfile>` sends the Dockerfile's parent directory as the Docker build context.
Add a `.dockerignore` next to the Dockerfile to keep local caches, generated artifacts, model files, or other unneeded paths out of the staged context.
NemoClaw still excludes credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` tries to include them.
NemoClaw sends user-supplied `--from` contexts to the OpenShell gateway builder and reserves its host-side local BuildKit prebuild for contexts that NemoClaw generates itself.
On a local Docker-driver gateway, a `Local BuildKit build skipped` notice is expected and the custom image build continues through the gateway.

```text
my-hermes-plugin-sandbox/
Expand Down
7 changes: 7 additions & 0 deletions docs/reference/commands-nemohermes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -342,6 +342,12 @@ If the staged context is larger than 100 MB, onboarding prints a warning before
Move the Dockerfile into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context.
If the directory contains unreadable files (for example, Windows system files visible in WSL), onboarding exits with an error suggesting you move the Dockerfile to a dedicated directory.

<Note>
NemoClaw builds user-supplied `--from` contexts with the OpenShell gateway builder.
The host-side local BuildKit prebuild is limited to build contexts generated entirely by NemoClaw.
On a local Docker-driver gateway, a `Local BuildKit build skipped` notice is expected and onboarding continues with the custom image.
</Note>

```bash
nemohermes onboard --from path/to/Dockerfile
```
Expand Down Expand Up @@ -400,6 +406,7 @@ Combining `--from <Dockerfile>` with non-interactive onboarding requires one of

Use a custom Dockerfile for the sandbox image.
This variant of `nemohermes onboard` accepts a `--from <Dockerfile>` argument to build the sandbox from a user-supplied Dockerfile instead of the default NemoClaw image.
The user-supplied context uses the OpenShell gateway builder instead of NemoClaw's host-side local BuildKit prebuild.

```bash
nemohermes onboard --from ./Dockerfile.custom
Expand Down
7 changes: 7 additions & 0 deletions docs/reference/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -446,6 +446,12 @@ If the staged context is larger than 100 MB, onboarding prints a warning before
Move the Dockerfile into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context.
If the directory contains unreadable files (for example, Windows system files visible in WSL), onboarding exits with an error suggesting you move the Dockerfile to a dedicated directory.

<Note>
NemoClaw builds user-supplied `--from` contexts with the OpenShell gateway builder.
The host-side local BuildKit prebuild is limited to build contexts generated entirely by NemoClaw.
On a local Docker-driver gateway, a `Local BuildKit build skipped` notice is expected and onboarding continues with the custom image.
</Note>

```bash
$$nemoclaw onboard --from path/to/Dockerfile
```
Expand Down Expand Up @@ -504,6 +510,7 @@ Combining `--from <Dockerfile>` with non-interactive onboarding requires one of

Use a custom Dockerfile for the sandbox image.
This variant of `$$nemoclaw onboard` accepts a `--from <Dockerfile>` argument to build the sandbox from a user-supplied Dockerfile instead of the default NemoClaw image.
The user-supplied context uses the OpenShell gateway builder instead of NemoClaw's host-side local BuildKit prebuild.

```bash
$$nemoclaw onboard --from ./Dockerfile.custom
Expand Down
3 changes: 2 additions & 1 deletion src/lib/agent/base-image.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ import {
dockerTag,
} from "../adapters/docker";
import { ROOT } from "../runner";
import { SANDBOX_BUILD_CONTEXT_PREFIX } from "../sandbox/build-context";
import {
buildLocalBaseTag,
createSandboxBaseImageResolutionKey,
Expand Down Expand Up @@ -324,7 +325,7 @@ export function createAgentSandbox(
}

const { imageTag: baseImageRef, resolutionMetadata } = ensureAgentBaseImage(agent, options);
const buildCtx = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-build-"));
const buildCtx = fs.mkdtempSync(path.join(os.tmpdir(), SANDBOX_BUILD_CONTEXT_PREFIX));
fs.cpSync(ROOT, buildCtx, {
recursive: true,
filter: (src) => {
Expand Down
7 changes: 6 additions & 1 deletion src/lib/onboard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2885,7 +2885,12 @@ async function createSandboxWithBaseImageResolution(
manageDashboard,
openshellShellCommand,
// Transitional BuildKit handoff removal is tracked by #6258.
prebuild: { buildCtx, buildId, dockerDriverGateway: isLinuxDockerDriverGatewayEnabled() },
prebuild: {
buildCtx,
buildId,
buildContextOrigin: fromDockerfile ? "custom" : "generated",
dockerDriverGateway: isLinuxDockerDriverGatewayEnabled(),
},
});
const dockerGpuCreatePatch = dockerGpuSandboxCreate.createDockerGpuSandboxCreatePatch({
enabled: useDockerGpuPatch,
Expand Down
3 changes: 2 additions & 1 deletion src/lib/onboard/build-context-stage.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import type { AgentDefinition } from "../agent/defs";
import { isErrnoException } from "../core/errno";
import {
collectBuildContextStats,
SANDBOX_BUILD_CONTEXT_PREFIX,
type StagedBuildContext,
stageOptimizedSandboxBuildContext,
} from "../sandbox/build-context";
Expand Down Expand Up @@ -92,7 +93,7 @@ export function stageCreateSandboxBuildContext(
" The --from flag sends the Dockerfile's parent directory to Docker; use a dedicated directory if this is not intentional.",
);
}
const buildCtx = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-build-"));
const buildCtx = fs.mkdtempSync(path.join(os.tmpdir(), SANDBOX_BUILD_CONTEXT_PREFIX));
const stagedDockerfile = path.join(buildCtx, "Dockerfile");
const cleanupCustomBuildCtx = (): void => {
try {
Expand Down
49 changes: 48 additions & 1 deletion src/lib/onboard/machine/live-flow-slice.test.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

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

import { createSession, type Session } from "../../state/onboard-session";
import {
Expand Down Expand Up @@ -69,6 +69,11 @@ function phase(
}

describe("runLiveOnboardFlowSlice", () => {
afterEach(() => {
vi.useRealTimers();
vi.restoreAllMocks();
});

it("uses the strict slice runner for fresh matching entry states", async () => {
const runSlice = vi.fn(async ({ context }) => ({
context: { value: context.value + 1 },
Expand Down Expand Up @@ -178,6 +183,48 @@ describe("runLiveOnboardFlowSlice", () => {
expect(applyCompatibleResult).toHaveBeenCalledOnce();
});

it("keeps compatibility phases visible through the default heartbeat reporter", async () => {
vi.useFakeTimers();
vi.setSystemTime(0);
const log = vi.spyOn(console, "log").mockImplementation(() => {});
let markPhaseStarted!: () => void;
let releasePhase!: () => void;
const phaseStarted = new Promise<void>((resolve) => {
markPhaseStarted = resolve;
});
const phaseReleased = new Promise<void>((resolve) => {
releasePhase = resolve;
});
const liveRuntime = runtime("provider_selection");
const pendingGateway: OnboardSequencePhase<Context> = {
state: "gateway",
async run(context) {
markPhaseStarted();
await phaseReleased;
return { context, result: advanceTo("inference") };
},
};

const running = runLiveOnboardFlowSlice({
context: { value: 1 },
runtime: liveRuntime.runtime,
phases: [pendingGateway],
runWhenState: ["gateway"],
compatibilityWhenState: ["provider_selection"],
runSlice: vi.fn(),
applyCompatibleResult: (result) => liveRuntime.applyResult(result),
});
await phaseStarted;
try {
await vi.advanceTimersByTimeAsync(30_000);
expect(log).toHaveBeenCalledWith(" ⏳ Still working on Gateway startup… (30s elapsed)");
} finally {
releasePhase();
await running;
}
expect(vi.getTimerCount()).toBe(0);
});

it("rejects non-resume states before the slice entry before running side effects", async () => {
const liveRuntime = runtime("init");
const blocked = phase("provider_selection", 2);
Expand Down
37 changes: 28 additions & 9 deletions src/lib/onboard/sandbox-create-launch.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,30 @@ import fs from "node:fs";
import os from "node:os";
import path from "node:path";

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

import { SANDBOX_BUILD_CONTEXT_PREFIX } from "../sandbox/build-context";
import { createOpenshellCliHelpers } from "./openshell-cli";
import {
prepareSandboxCreateLaunch,
prepareSandboxCreateLaunchWithPrebuild,
} from "./sandbox-create-launch";

const disabledHermesDashboardState = { config: null, enabled: false };
const temporaryBuildContexts: string[] = [];

function createTrustedBuildContext(): string {
const buildCtx = fs.mkdtempSync(path.join(os.tmpdir(), SANDBOX_BUILD_CONTEXT_PREFIX));
temporaryBuildContexts.push(buildCtx);
fs.writeFileSync(path.join(buildCtx, "Dockerfile"), "FROM scratch\n");
return buildCtx;
}

afterEach(() => {
for (const buildCtx of temporaryBuildContexts.splice(0)) {
fs.rmSync(buildCtx, { recursive: true, force: true });
}
});

describe("prepareSandboxCreateLaunch", () => {
it("builds the sandbox create command and runtime env envelope", () => {
Expand Down Expand Up @@ -265,11 +280,13 @@ describe("prepareSandboxCreateLaunch", () => {

describe("prepareSandboxCreateLaunchWithPrebuild", () => {
it("hands the build-qualified image to the canonical launch renderer", async () => {
const buildCtx = createTrustedBuildContext();
const dockerfile = path.join(buildCtx, "Dockerfile");
const buildImage = vi.fn(async () => 0);
const result = await prepareSandboxCreateLaunchWithPrebuild({
agent: null,
chatUiUrl: "",
createArgs: ["--from", "/tmp/build/Dockerfile", "--name", "demo"],
createArgs: ["--from", dockerfile, "--name", "demo"],
env: {},
extraPlaceholderKeys: [],
getDashboardForwardPort: () => "0",
Expand All @@ -279,8 +296,9 @@ describe("prepareSandboxCreateLaunchWithPrebuild", () => {
sandboxName: "demo",
buildEnv: () => ({}),
prebuild: {
buildCtx: "/tmp/build",
buildCtx,
buildId: "build-123",
buildContextOrigin: "generated",
dockerDriverGateway: true,
env: { NEMOCLAW_SANDBOX_PREBUILD: "1" },
buildImage,
Expand All @@ -299,10 +317,12 @@ describe("prepareSandboxCreateLaunchWithPrebuild", () => {
});

it("renders the original Dockerfile after a local build failure", async () => {
const buildCtx = createTrustedBuildContext();
const dockerfile = path.join(buildCtx, "Dockerfile");
const result = await prepareSandboxCreateLaunchWithPrebuild({
agent: null,
chatUiUrl: "",
createArgs: ["--from", "/tmp/build/Dockerfile", "--name", "demo"],
createArgs: ["--from", dockerfile, "--name", "demo"],
env: {},
extraPlaceholderKeys: [],
getDashboardForwardPort: () => "0",
Expand All @@ -312,8 +332,9 @@ describe("prepareSandboxCreateLaunchWithPrebuild", () => {
sandboxName: "demo",
buildEnv: () => ({}),
prebuild: {
buildCtx: "/tmp/build",
buildCtx,
buildId: "build-123",
buildContextOrigin: "generated",
dockerDriverGateway: true,
env: { NEMOCLAW_SANDBOX_PREBUILD: "1" },
buildImage: async () => 1,
Expand All @@ -322,12 +343,10 @@ describe("prepareSandboxCreateLaunchWithPrebuild", () => {
});

expect(result.prebuild).toEqual({
createArgs: ["--from", "/tmp/build/Dockerfile", "--name", "demo"],
createArgs: ["--from", dockerfile, "--name", "demo"],
imageRef: null,
});
expect(result.createCommand).toContain(
"sandbox create --from /tmp/build/Dockerfile --name demo",
);
expect(result.createCommand).toContain(`sandbox create --from ${dockerfile} --name demo`);
expect(result.createCommand).not.toContain("nemoclaw-sandbox-local");
});
});
Loading
Loading