@openclaw/openshell-sandbox 2026.8.1-beta.2 → 2026.9.1-beta.1

package/README.md

@@ -2,7 +2,13 @@
 
 Official NVIDIA OpenShell sandbox backend for OpenClaw.
 
-This plugin lets OpenClaw use OpenShell-managed sandboxes with mirrored local workspaces and SSH command execution.
+This plugin lets OpenClaw use OpenShell-managed local or remote sandboxes with
+SSH command execution. Choose `mirror` mode for a synchronized local workspace
+or `remote` mode for a remote-canonical workspace.
+
+Mirror operations sharing a workspace run sequentially so concurrent agent
+turns cannot overwrite one another. Outbound attachments resolve against the
+configured remote workspace, which defaults to `/sandbox`.
 
 Configuring an OpenShell workspace requires OpenShell `v0.0.88` or newer. The
 plugin supports OpenShell control-plane workspaces through
@@ -22,6 +28,23 @@ Restart the Gateway after installing or updating the plugin.
 
 ## Configure
 
+Install and configure the OpenShell CLI before enabling the backend. As the same
+operating system user that runs the OpenClaw Gateway, verify:
+
+```bash
+openshell --version
+openshell gateway list
+openshell sandbox list
+```
+
+Set `agents.defaults.sandbox.backend` to `"openshell"`, enable
+`plugins.entries.openshell`, and restart the OpenClaw Gateway. OpenShell
+settings belong under `plugins.entries.openshell.config`.
+
+The optional `policy` setting must be the path to a readable OpenShell policy
+YAML file on the Gateway host; it is not a policy name or ID. Use an absolute
+path to avoid resolving it relative to an agent workspace.
+
 Use the OpenShell docs for credentials, workspace mirroring, runtime selection, and troubleshooting:
 
 - https://docs.openclaw.ai/gateway/openshell

package/dist/index.js

@@ -1,15 +1,16 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
-import { buildRemoteWorkdirValidationCommand, buildValidatedExecRemoteCommand, createRemoteShellSandboxFsBridge, createSshSandboxSessionFromConfigText, createWritableRenameTargetResolver, disposeSshSandboxSession, registerSandboxBackend, resolvePreferredOpenClawTmpDir, runPluginCommandWithTimeout, runSshSandboxCommand, sanitizeEnvVars, shellEscape, withTempWorkspace } from "openclaw/plugin-sdk/sandbox";
+import { buildRemoteCommand, buildRemoteWorkdirValidationCommand, buildValidatedExecRemoteCommand, createRemoteShellSandboxFsBridge, createSshSandboxSessionFromConfigText, createWritableRenameTargetResolver, disposeSshSandboxSession, prepareSshSandboxExec, registerSandboxBackend, resolvePreferredOpenClawTmpDir, runPluginCommandWithTimeout, runSshSandboxCommand, sanitizeEnvVars, shellEscape, withTempWorkspace } from "openclaw/plugin-sdk/sandbox";
 import { createHash } from "node:crypto";
 import fsPromises from "node:fs/promises";
 import path from "node:path";
+import { createDeferred, formatPluginConfigIssue, mapPluginConfigIssues } from "openclaw/plugin-sdk/extension-shared";
+import { KeyedAsyncQueue } from "openclaw/plugin-sdk/keyed-async-queue";
 import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { buildPluginConfigSchema } from "openclaw/plugin-sdk/core";
-import { formatPluginConfigIssue, mapPluginConfigIssues } from "openclaw/plugin-sdk/extension-shared";
 import { MAX_TIMER_TIMEOUT_SECONDS } from "openclaw/plugin-sdk/number-runtime";
 import { z } from "zod";
-import { root } from "openclaw/plugin-sdk/file-access-runtime";
-import { FsSafeError, isPathInside, movePathWithCopyFallback } from "openclaw/plugin-sdk/security-runtime";
+import { isPathInside, root } from "openclaw/plugin-sdk/file-access-runtime";
+import { FsSafeError, movePathWithCopyFallback } from "openclaw/plugin-sdk/security-runtime";
 import pLimit from "p-limit";
 //#region extensions/openshell/src/cli.ts
 function buildOpenShellBaseArgv(config) {
@@ -19,9 +20,6 @@ function buildOpenShellBaseArgv(config) {
 	if (config.workspace) argv.push("--workspace", config.workspace);
 	return argv;
 }
-function buildRemoteCommand(argv) {
-	return argv.map((entry) => shellEscape(entry)).join(" ");
-}
 function applyGatewayEndpointToSshConfig(params) {
 	const endpoint = params.gatewayEndpoint?.trim();
 	if (!endpoint) return params.configText;
@@ -75,6 +73,7 @@ function normalizeProviders(value) {
 	return providers;
 }
 const nonEmptyTrimmedString = (message) => z.string({ error: message }).trim().min(1, { error: message });
+const openShellManagedRemotePath = (fieldName) => nonEmptyTrimmedString(`${fieldName} must be a non-empty string`).regex(/^\/(?:sandbox|agent)(?:\/|$)/, { error: (issue) => String(issue.input).startsWith("/") ? `OpenShell ${fieldName} must stay under /sandbox or /agent` : `OpenShell ${fieldName} must be absolute` }).refine((value) => isManagedOpenShellRemotePath(path.posix.normalize(value)), { error: `OpenShell ${fieldName} must stay under /sandbox or /agent` });
 const openShellWorkspaceName = z.string({ error: "workspace must be a valid OpenShell workspace name" }).trim().min(1, { error: "workspace must be a valid OpenShell workspace name" }).max(19, { error: "workspace must be at most 19 characters" }).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { error: "workspace must contain lowercase alphanumeric characters or single hyphens and must not start or end with a hyphen" });
 const OpenShellPluginConfigSchema = z.strictObject({
 	mode: z.enum(["mirror", "remote"], { error: "mode must be one of mirror, remote" }).optional(),
@@ -87,8 +86,8 @@ const OpenShellPluginConfigSchema = z.strictObject({
 	providers: z.array(z.string({ error: "providers must be an array of strings" }).trim().min(1, { error: "providers must be an array of strings" }), { error: "providers must be an array of strings" }).optional(),
 	gpu: z.boolean({ error: "gpu must be a boolean" }).optional(),
 	autoProviders: z.boolean({ error: "autoProviders must be a boolean" }).optional(),
-	remoteWorkspaceDir: nonEmptyTrimmedString("remoteWorkspaceDir must be a non-empty string").optional(),
-	remoteAgentWorkspaceDir: nonEmptyTrimmedString("remoteAgentWorkspaceDir must be a non-empty string").optional(),
+	remoteWorkspaceDir: openShellManagedRemotePath("remoteWorkspaceDir").optional(),
+	remoteAgentWorkspaceDir: openShellManagedRemotePath("remoteAgentWorkspaceDir").optional(),
 	timeoutSeconds: z.number({ error: `timeoutSeconds must be a number between 1 and ${MAX_TIMER_TIMEOUT_SECONDS}` }).min(1, { error: "timeoutSeconds must be a number >= 1" }).max(MAX_TIMER_TIMEOUT_SECONDS, { error: `timeoutSeconds must be a number <= ${MAX_TIMER_TIMEOUT_SECONDS}` }).optional()
 });
 function isManagedOpenShellRemotePath(value) {
@@ -354,8 +353,10 @@ var OpenShellFsBridge = class {
 		}
 		if (input.startsWith(`${workspaceContainerRoot}/`) || input === workspaceContainerRoot) {
 			const relative = path.posix.relative(workspaceContainerRoot, input) || "";
+			const hostPath = relative ? path.resolve(workspaceRoot, ...relative.split("/")) : workspaceRoot;
+			if (!isPathInside(workspaceRoot, hostPath)) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${input}`);
 			return {
-				hostPath: relative ? path.resolve(workspaceRoot, ...relative.split("/")) : workspaceRoot,
+				hostPath,
 				relativePath: relative,
 				containerPath: relative ? path.posix.join(workspaceContainerRoot, relative) : workspaceContainerRoot,
 				mountHostRoot: workspaceRoot,
@@ -365,8 +366,10 @@ var OpenShellFsBridge = class {
 		}
 		if (hasAgentMount && (input.startsWith(`${agentContainerRoot}/`) || input === agentContainerRoot)) {
 			const relative = path.posix.relative(agentContainerRoot, input) || "";
+			const hostPath = relative ? path.resolve(agentRoot, ...relative.split("/")) : agentRoot;
+			if (!isPathInside(agentRoot, hostPath)) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${input}`);
 			return {
-				hostPath: relative ? path.resolve(agentRoot, ...relative.split("/")) : agentRoot,
+				hostPath,
 				relativePath: relative ? agentContainerRoot + "/" + relative : agentContainerRoot,
 				containerPath: relative ? path.posix.join(agentContainerRoot, relative) : agentContainerRoot,
 				mountHostRoot: agentRoot,
@@ -645,6 +648,8 @@ async function stageDirectoryContents(params) {
 }
 //#endregion
 //#region extensions/openshell/src/backend.ts
+const openShellWorkspaceOperations = new KeyedAsyncQueue();
+let openShellDetachedCreateSupport;
 const MATERIALIZED_SKILLS_REMOTE_PARTS = [".openclaw", "sandbox-skills"];
 function buildOpenShellDirectoryUploadArgs(params) {
 	return [
@@ -653,9 +658,10 @@ function buildOpenShellDirectoryUploadArgs(params) {
 		"--no-git-ignore",
 		params.sandboxName,
 		params.localPath,
-		normalizeRemotePath(params.remotePath)
+		`${normalizeRemotePath(params.remotePath)}/`
 	];
 }
+const REMOTE_MANAGED_ROOTS_EMPTY_SCRIPT = "for root in \"$@\"; do if [ -d \"$root\" ] && [ -n \"$(ls -A \"$root\")\" ]; then printf \"1\\n\"; exit 0; fi; done; printf \"0\\n\"";
 const PINNED_REMOTE_PATH_MUTATION_SCRIPT = [
 	"set -eu",
 	"die() { echo \"$1\" >&2; exit 1; }",
@@ -818,20 +824,22 @@ function createOpenShellSandboxBackendManager(params) {
 				args: [
 					"sandbox",
 					"get",
-					entry.containerName
+					entry.containerName,
+					"--output",
+					"json"
 				]
 			});
 			const configuredSource = execContext.config.from;
 			return {
-				running: result.code === 0,
+				running: result.code === 0 && parseOpenShellSandboxPhase(result.stdout) === "Ready",
 				actualConfigLabel: entry.image,
 				configLabelMatch: entry.image === configuredSource
 			};
 		},
-		async removeRuntime({ entry }) {
-			await runOpenShellCli({
+		async removeRuntime({ entry, config }) {
+			const result = await runOpenShellCli({
 				context: {
-					config: params.pluginConfig,
+					config: resolveOpenShellPluginConfigFromConfig(config, params.pluginConfig),
 					sandboxName: entry.containerName
 				},
 				args: [
@@ -840,6 +848,7 @@ function createOpenShellSandboxBackendManager(params) {
 					entry.containerName
 				]
 			});
+			if (result.code !== 0) throw new Error(result.stderr.trim() || "openshell sandbox delete failed");
 		}
 	};
 }
@@ -854,69 +863,25 @@ async function createOpenShellSandboxBackend(params) {
 		config: params.pluginConfig,
 		sandboxName
 	};
-	const impl = new OpenShellSandboxBackendImpl({
+	return new OpenShellSandboxBackendImpl({
 		createParams: params.createParams,
 		execContext,
 		legacyRuntimeAdopted: resolvedSandboxName.legacyRuntimeAdopted,
 		remoteWorkspaceDir: params.pluginConfig.remoteWorkspaceDir,
 		remoteAgentWorkspaceDir: params.pluginConfig.remoteAgentWorkspaceDir
-	});
-	return {
-		id: "openshell",
-		runtimeId: sandboxName,
-		runtimeLabel: sandboxName,
-		workdir: params.pluginConfig.remoteWorkspaceDir,
-		env: params.createParams.cfg.docker.env,
-		mode: params.pluginConfig.mode,
-		configLabel: params.pluginConfig.from,
-		configLabelKind: "Source",
-		workdirValidation: "backend",
-		validateWorkdir: async (workdir) => await impl.validateWorkdir(workdir),
-		discardPreparedWorkdir: (workdir) => impl.discardPreparedWorkdir(workdir),
-		workdirRoots: [params.pluginConfig.remoteWorkspaceDir, params.pluginConfig.remoteAgentWorkspaceDir],
-		buildExecSpec: async ({ command, workdir, env, usePty }) => {
-			const pending = await impl.prepareExec({
-				command,
-				workdir,
-				env,
-				usePty
-			});
-			return {
-				argv: pending.argv,
-				env: buildOpenShellSshExecEnv(),
-				stdinMode: "pipe-open",
-				finalizeToken: pending.token
-			};
-		},
-		finalizeExec: async ({ token }) => {
-			await impl.finalizeExec(token);
-		},
-		runShellCommand: async (command) => await impl.runRemoteShellScript(command),
-		createFsBridge: ({ sandbox }) => params.pluginConfig.mode === "remote" ? createRemoteShellSandboxFsBridge({
-			sandbox,
-			runtime: impl.asHandle()
-		}) : createOpenShellFsBridge({
-			sandbox,
-			backend: impl.asHandle()
-		}),
-		remoteWorkspaceDir: params.pluginConfig.remoteWorkspaceDir,
-		remoteAgentWorkspaceDir: params.pluginConfig.remoteAgentWorkspaceDir,
-		runRemoteShellScript: async (command) => await impl.runRemoteShellScript(command),
-		mkdirpRemotePath: async (remotePath, signal) => await impl.mkdirpRemotePath(remotePath, signal),
-		removeRemotePath: async (remotePath, removeParams) => await impl.removeRemotePath(remotePath, removeParams),
-		renameRemotePath: async (fromRemotePath, toRemotePath, signal) => await impl.renameRemotePath(fromRemotePath, toRemotePath, signal),
-		syncLocalPathToRemote: async (localPath, remotePath) => await impl.syncLocalPathToRemote(localPath, remotePath)
-	};
+	}).asHandle();
 }
 var OpenShellSandboxBackendImpl = class {
 	constructor(params) {
 		this.params = params;
+		this.handle = null;
 		this.ensurePromise = null;
 		this.preparedRemoteWorkspaceForNextExec = null;
 		this.remoteSeedPending = false;
 	}
 	asHandle() {
-		return {
+		if (this.handle) return this.handle;
+		const handle = {
 			id: "openshell",
 			runtimeId: this.params.execContext.sandboxName,
 			runtimeLabel: this.params.execContext.sandboxName,
@@ -948,58 +913,121 @@ var OpenShellSandboxBackendImpl = class {
 			finalizeExec: async ({ token }) => {
 				await this.finalizeExec(token);
 			},
-			runShellCommand: async (command) => await this.runRemoteShellScript(command),
+			runShellCommand: async (command) => await this.runWorkspaceOperation(async () => await this.runRemoteShellScript(command)),
 			createFsBridge: ({ sandbox }) => this.params.execContext.config.mode === "remote" ? createRemoteShellSandboxFsBridge({
 				sandbox,
-				runtime: this.asHandle()
-			}) : createOpenShellFsBridge({
-				sandbox,
-				backend: this.asHandle()
-			}),
-			runRemoteShellScript: async (command) => await this.runRemoteShellScript(command),
-			mkdirpRemotePath: async (remotePath, signal) => await this.mkdirpRemotePath(remotePath, signal),
-			removeRemotePath: async (remotePath, removeParams) => await this.removeRemotePath(remotePath, removeParams),
-			renameRemotePath: async (fromRemotePath, toRemotePath, signal) => await this.renameRemotePath(fromRemotePath, toRemotePath, signal),
-			syncLocalPathToRemote: async (localPath, remotePath) => await this.syncLocalPathToRemote(localPath, remotePath)
+				runtime: handle
+			}) : this.createMirrorFsBridge(sandbox),
+			runRemoteShellScript: async (command) => await this.runWorkspaceOperation(async () => await this.runRemoteShellScript(command))
 		};
+		this.handle = handle;
+		return handle;
+	}
+	createMirrorFsBridge(sandbox) {
+		const bridge = createOpenShellFsBridge({
+			sandbox,
+			backend: {
+				remoteAgentWorkspaceDir: this.params.remoteAgentWorkspaceDir,
+				mkdirpRemotePath: (remotePath, signal) => this.mkdirpRemotePath(remotePath, signal),
+				removeRemotePath: (remotePath, params) => this.removeRemotePath(remotePath, params),
+				renameRemotePath: (from, to, signal) => this.renameRemotePath(from, to, signal),
+				syncLocalPathToRemote: (localPath, remotePath) => this.syncLocalPathToRemote(localPath, remotePath)
+			}
+		});
+		return {
+			resolvePath: (params) => bridge.resolvePath(params),
+			readFile: (params) => this.runWorkspaceOperation(() => bridge.readFile(params)),
+			writeFile: (params) => this.runWorkspaceOperation(() => bridge.writeFile(params)),
+			createFileExclusive: (params) => this.runWorkspaceOperation(() => bridge.createFileExclusive(params)),
+			mkdirp: (params) => this.runWorkspaceOperation(() => bridge.mkdirp(params)),
+			remove: (params) => this.runWorkspaceOperation(() => bridge.remove(params)),
+			rename: (params) => this.runWorkspaceOperation(() => bridge.rename(params)),
+			stat: (params) => this.runWorkspaceOperation(() => bridge.stat(params))
+		};
+	}
+	async runWorkspaceOperation(operation) {
+		const lease = await this.acquireWorkspaceLease();
+		try {
+			return await operation();
+		} finally {
+			lease.release();
+		}
+	}
+	async acquireWorkspaceLease() {
+		const { config, sandboxName } = this.params.execContext;
+		const keys = [`host:${path.resolve(this.params.createParams.workspaceDir)}`, `runtime:${JSON.stringify([
+			config.gatewayEndpoint ?? "",
+			config.gateway ?? "",
+			config.workspace ?? process.env.OPENSHELL_WORKSPACE ?? "",
+			sandboxName
+		])}`].toSorted();
+		const releases = [];
+		try {
+			for (const key of keys) {
+				const acquired = createDeferred();
+				const released = createDeferred();
+				openShellWorkspaceOperations.enqueue(key, async () => {
+					acquired.resolve();
+					await released.promise;
+				});
+				await acquired.promise;
+				releases.push(released.resolve);
+			}
+		} catch (error) {
+			for (const release of releases.toReversed()) release();
+			throw error;
+		}
+		let active = true;
+		return { release: () => {
+			if (!active) return;
+			active = false;
+			for (const release of releases.toReversed()) release();
+		} };
 	}
 	async prepareExec(params) {
 		const remoteWorkdir = params.workdir ?? this.params.remoteWorkspaceDir;
-		const preparedWorkspace = this.consumePreparedRemoteWorkspaceForNextExec(remoteWorkdir);
 		const remoteCommand = buildValidatedExecRemoteCommand({
 			command: params.command,
 			workdir: remoteWorkdir,
-			env: params.env
+			env: {}
 		});
-		await (preparedWorkspace ?? this.prepareRemoteWorkspaceForExec());
-		const sshSession = await createOpenShellSshSession({ context: this.params.execContext });
-		return {
-			argv: [
-				"ssh",
-				"-F",
-				sshSession.configPath,
-				...params.usePty ? [
-					"-tt",
-					"-o",
-					"RequestTTY=force",
-					"-o",
-					"SetEnv=TERM=xterm-256color"
-				] : [
-					"-T",
-					"-o",
-					"RequestTTY=no"
-				],
-				sshSession.host,
-				remoteCommand
-			],
-			token: { sshSession }
-		};
+		const preparedWorkspace = this.consumePreparedRemoteWorkspaceForNextExec(remoteWorkdir);
+		const workspaceLease = preparedWorkspace?.lease ?? await this.acquireWorkspaceLease();
+		try {
+			await (preparedWorkspace?.promise ?? this.prepareRemoteWorkspaceForExec());
+			const sshSession = await createOpenShellSshSession({ context: this.params.execContext });
+			try {
+				const prepared = await prepareSshSandboxExec({
+					session: sshSession,
+					remoteCommand,
+					env: params.env,
+					tty: params.usePty
+				});
+				return {
+					argv: prepared.argv,
+					token: {
+						sshSession,
+						cleanup: prepared.cleanup,
+						workspaceLease
+					}
+				};
+			} catch (error) {
+				await disposeSshSandboxSession(sshSession);
+				throw error;
+			}
+		} catch (error) {
+			workspaceLease.release();
+			throw error;
+		}
 	}
 	async validateWorkdir(workdir) {
+		this.discardPreparedRemoteWorkspace();
+		const lease = await this.acquireWorkspaceLease();
 		const preparedWorkspace = this.prepareRemoteWorkspaceForExec();
 		const reusablePreparation = {
 			workdir,
-			promise: preparedWorkspace
+			promise: preparedWorkspace,
+			lease
 		};
 		this.preparedRemoteWorkspaceForNextExec = reusablePreparation;
 		try {
@@ -1015,16 +1043,21 @@ var OpenShellSandboxBackendImpl = class {
 					allowFailure: true
 				});
 				const resolvedWorkdir = result.code === 0 ? result.stdout.toString("utf8").trim() : "";
-				if (this.preparedRemoteWorkspaceForNextExec === reusablePreparation) this.preparedRemoteWorkspaceForNextExec = resolvedWorkdir ? {
-					workdir: resolvedWorkdir,
-					promise: preparedWorkspace
-				} : null;
+				if (this.preparedRemoteWorkspaceForNextExec === reusablePreparation) {
+					this.preparedRemoteWorkspaceForNextExec = resolvedWorkdir ? {
+						workdir: resolvedWorkdir,
+						promise: preparedWorkspace,
+						lease
+					} : null;
+					if (!resolvedWorkdir) lease.release();
+				} else lease.release();
 				return resolvedWorkdir || null;
 			} finally {
 				await disposeSshSandboxSession(sshSession);
 			}
 		} catch (error) {
-			if (this.preparedRemoteWorkspaceForNextExec === reusablePreparation) this.preparedRemoteWorkspaceForNextExec = null;
+			if (this.preparedRemoteWorkspaceForNextExec?.lease === lease) this.preparedRemoteWorkspaceForNextExec = null;
+			lease.release();
 			throw error;
 		}
 	}
@@ -1039,14 +1072,20 @@ var OpenShellSandboxBackendImpl = class {
 	consumePreparedRemoteWorkspaceForNextExec(workdir) {
 		const preparedWorkspace = this.preparedRemoteWorkspaceForNextExec;
 		if (!preparedWorkspace || preparedWorkspace.workdir !== workdir) {
-			this.preparedRemoteWorkspaceForNextExec = null;
+			this.discardPreparedRemoteWorkspace();
 			return null;
 		}
 		this.preparedRemoteWorkspaceForNextExec = null;
-		return preparedWorkspace.promise;
+		return preparedWorkspace;
 	}
 	discardPreparedWorkdir(workdir) {
-		if (this.preparedRemoteWorkspaceForNextExec?.workdir === workdir) this.preparedRemoteWorkspaceForNextExec = null;
+		if (this.preparedRemoteWorkspaceForNextExec?.workdir === workdir) this.discardPreparedRemoteWorkspace();
+	}
+	discardPreparedRemoteWorkspace() {
+		const preparedWorkspace = this.preparedRemoteWorkspaceForNextExec;
+		if (!preparedWorkspace) return;
+		this.preparedRemoteWorkspaceForNextExec = null;
+		preparedWorkspace.promise.then(() => preparedWorkspace.lease.release(), () => preparedWorkspace.lease.release());
 	}
 	async prepareRemoteWorkspaceForExec() {
 		await this.ensureSandboxExists();
@@ -1057,10 +1096,19 @@ var OpenShellSandboxBackendImpl = class {
 		if (!await this.maybeSeedRemoteWorkspace()) await this.syncSkillsWorkspaceToRemote();
 	}
 	async finalizeExec(token) {
+		const workspaceLease = token?.workspaceLease ?? await this.acquireWorkspaceLease();
 		try {
 			if (this.params.execContext.config.mode === "mirror") await this.syncWorkspaceFromRemote();
 		} finally {
-			if (token?.sshSession) await disposeSshSandboxSession(token.sshSession);
+			try {
+				if (token?.sshSession) try {
+					await token.cleanup();
+				} finally {
+					await disposeSshSandboxSession(token.sshSession);
+				}
+			} finally {
+				workspaceLease.release();
+			}
 		}
 	}
 	async runRemoteShellScript(params) {
@@ -1170,7 +1218,7 @@ var OpenShellSandboxBackendImpl = class {
 				"--no-git-ignore",
 				this.params.execContext.sandboxName,
 				localPath,
-				path.posix.dirname(remotePath)
+				remotePath
 			],
 			cwd: this.params.createParams.workspaceDir
 		});
@@ -1221,9 +1269,12 @@ var OpenShellSandboxBackendImpl = class {
 				if (!phase) throw this.buildLegacyRuntimeUnavailableError("OpenShell did not report a lifecycle phase for this sandbox.");
 				if (phase !== "Ready") throw this.buildLegacyRuntimeUnavailableError(`OpenShell reports phase "${phase}".`);
 			}
+			if (this.params.execContext.config.mode === "remote" && await this.remoteManagedRootsEmpty()) this.remoteSeedPending = true;
 			return;
 		}
 		if (this.params.legacyRuntimeAdopted) throw this.buildLegacyRuntimeUnavailableError(getResult.stderr.trim());
+		if (!/\bsandbox not found\b/iu.test(getResult.stderr)) throw new Error(getResult.stderr.trim() || "openshell sandbox get failed");
+		const detachedCreateSupported = await this.supportsDetachedSandboxCreation();
 		const createArgs = [
 			"sandbox",
 			"create",
@@ -1235,8 +1286,12 @@ var OpenShellSandboxBackendImpl = class {
 			...this.params.execContext.config.gpu ? ["--gpu"] : [],
 			...this.params.execContext.config.autoProviders ? ["--auto-providers"] : ["--no-auto-providers"],
 			...this.params.execContext.config.providers.flatMap((provider) => ["--provider", provider]),
-			"--",
-			"true"
+			...detachedCreateSupported ? [
+				"--detach",
+				"--",
+				"sleep",
+				"infinity"
+			] : ["--", "true"]
 		];
 		const createResult = await runOpenShellCli({
 			context: this.params.execContext,
@@ -1247,6 +1302,41 @@ var OpenShellSandboxBackendImpl = class {
 		if (createResult.code !== 0) throw new Error(createResult.stderr.trim() || "openshell sandbox create failed");
 		this.remoteSeedPending = true;
 	}
+	async supportsDetachedSandboxCreation() {
+		const { config } = this.params.execContext;
+		const cliIdentity = JSON.stringify([
+			config.command,
+			config.gatewayEndpoint ?? "",
+			config.gateway ?? "",
+			config.workspace ?? process.env.OPENSHELL_WORKSPACE ?? ""
+		]);
+		let support = openShellDetachedCreateSupport?.key === cliIdentity ? openShellDetachedCreateSupport.promise : void 0;
+		if (!support) {
+			support = (async () => {
+				const result = await runOpenShellCli({
+					context: this.params.execContext,
+					args: [
+						"sandbox",
+						"create",
+						"--help"
+					],
+					cwd: this.params.createParams.workspaceDir
+				});
+				if (result.code !== 0) throw new Error(result.stderr.trim() || "openshell sandbox create capability check failed");
+				return /^\s*--detach(?:\s|$)/mu.test(result.stdout);
+			})();
+			openShellDetachedCreateSupport = {
+				key: cliIdentity,
+				promise: support
+			};
+		}
+		try {
+			return await support;
+		} catch (error) {
+			if (openShellDetachedCreateSupport?.promise === support) openShellDetachedCreateSupport = void 0;
+			throw error;
+		}
+	}
 	async resolveLegacyRuntimePhase() {
 		const pageSize = 100;
 		for (let offset = 0;; offset += pageSize) {
@@ -1350,7 +1440,8 @@ var OpenShellSandboxBackendImpl = class {
 			const stagedRoot = path.join(tmpDir, remoteRootName);
 			await stageDirectoryContents({
 				sourceDir: localPath,
-				targetDir: stagedRoot
+				targetDir: stagedRoot,
+				excludeDirs: DEFAULT_OPEN_SHELL_MIRROR_EXCLUDE_DIRS
 			});
 			const stagedEntries = (await fsPromises.readdir(stagedRoot)).toSorted();
 			for (const entry of stagedEntries) {
@@ -1367,6 +1458,12 @@ var OpenShellSandboxBackendImpl = class {
 			}
 		});
 	}
+	async remoteManagedRootsEmpty() {
+		return (await this.runRemoteShellScriptInternal({
+			script: REMOTE_MANAGED_ROOTS_EMPTY_SCRIPT,
+			args: [this.params.remoteWorkspaceDir, this.params.remoteAgentWorkspaceDir]
+		})).stdout.toString("utf8").trim() === "0";
+	}
 	async maybeSeedRemoteWorkspace() {
 		if (!this.remoteSeedPending) return false;
 		this.remoteSeedPending = false;
@@ -1431,6 +1528,15 @@ function parseOpenShellSandboxPhasePage(stdout, sandboxName) {
 		return;
 	}
 }
+function parseOpenShellSandboxPhase(stdout) {
+	try {
+		const parsed = JSON.parse(stdout);
+		if (typeof parsed !== "object" || parsed === null || !("phase" in parsed)) return;
+		return typeof parsed.phase === "string" ? parsed.phase : void 0;
+	} catch {
+		return;
+	}
+}
 function resolveRemoteMaterializedSkillsWorkspaceDir(remoteWorkspaceDir) {
 	const root = remoteWorkspaceDir.replace(/\\/g, "/").replace(/\/+$/, "") || "/";
 	return path.posix.join(root, ...MATERIALIZED_SKILLS_REMOTE_PARTS);

package/openclaw.plugin.json

@@ -54,11 +54,13 @@
       },
       "remoteWorkspaceDir": {
         "type": "string",
-        "minLength": 1
+        "minLength": 1,
+        "pattern": "^\\/(?:sandbox|agent)(?:\\/|$)"
       },
       "remoteAgentWorkspaceDir": {
         "type": "string",
-        "minLength": 1
+        "minLength": 1,
+        "pattern": "^\\/(?:sandbox|agent)(?:\\/|$)"
       },
       "timeoutSeconds": {
         "type": "number",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/openshell-sandbox",
-  "version": "2026.8.1-beta.2",
+  "version": "2026.9.1-beta.1",
   "description": "OpenClaw sandbox backend for the NVIDIA OpenShell CLI with mirrored local workspaces and SSH command execution.",
   "repository": {
     "type": "git",
@@ -21,10 +21,10 @@
       "minHostVersion": ">=2026.5.12-beta.1"
     },
     "compat": {
-      "pluginApi": ">=2026.8.1-beta.2"
+      "pluginApi": ">=2026.9.1-beta.1"
     },
     "build": {
-      "openclawVersion": "2026.8.1-beta.2",
+      "openclawVersion": "2026.9.1-beta.1",
       "bundledDist": false
     },
     "release": {
@@ -41,7 +41,7 @@
     "README.md"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.8.1-beta.2"
+    "openclaw": ">=2026.9.1-beta.1"
   },
   "peerDependenciesMeta": {
     "openclaw": {