@@ -21,6 +21,7 @@
 import io.agentscope.harness.agent.sandbox.WorkspaceSpec;
 import io.agentscope.harness.agent.sandbox.snapshot.NoopSnapshotSpec;
 import io.agentscope.harness.agent.sandbox.snapshot.SandboxSnapshotSpec;
+import java.util.List;
 import java.util.function.Supplier;
 
 /** {@link SandboxFilesystemSpec} for E2B cloud sandboxes. */
@@ -110,6 +111,30 @@ public E2bFilesystemSpec codec(E2bCodec codec) {
         return this;
     }
 
+    public E2bFilesystemSpec volumeMount(String name, String path) {
+        options.addVolumeMount(name, path);
+        return this;
+    }
+
+    public E2bFilesystemSpec volumeMount(E2bVolumeMount mount) {
+        options.addVolumeMount(mount);
+        return this;
+    }
+
+    /**
+     * Replaces all configured volume mounts.
+     *
+     * <p>A null or empty list clears mounts on this spec, but note that {@link E2bSandboxClient}
+     * merging treats an empty call-level list as "not set" (same convention as AgentRun OSS
+     * mounts), so clearing only takes effect when these options are also the client defaults.
+     *
+     * @param mounts replacement mounts (null or empty clears previously added ones)
+     */
+    public E2bFilesystemSpec volumeMounts(List<E2bVolumeMount> mounts) {
+        options.setVolumeMounts(mounts);
+        return this;
+    }
+
     public E2bFilesystemSpec connectTimeoutSeconds(int connectTimeoutSeconds) {
         options.setConnectTimeoutSeconds(connectTimeoutSeconds);
         return this;
 
@@ -61,18 +61,50 @@ final class E2bPlatformHttp {
     }
 
     JsonNode createSandbox(String templateId, int timeoutSeconds) throws IOException {
-        return createSandbox(templateId, timeoutSeconds, Map.of());
+        return createSandbox(templateId, timeoutSeconds, null, null);
     }
 
     JsonNode createSandbox(String templateId, int timeoutSeconds, Map<String, String> envVars)
             throws IOException {
+        return createSandbox(templateId, timeoutSeconds, null, envVars);
+    }
+
+    /**
+     * Creates a sandbox, mounting pre-existing volumes when {@code mounts} is non-empty.
+     *
+     * <p>Mounts are serialized as {@code volumeMounts: [{name, path}]} per the platform REST API.
+     * The field is omitted when empty. Platform 400s (no volume beta access, unknown volume name)
+     * propagate with the response body via {@link #postJson}.
+     */
+    JsonNode createSandbox(
+            String templateId,
+            int timeoutSeconds,
+            List<E2bVolumeMount> mounts,
+            Map<String, String> envVars)
+            throws IOException {
         ObjectNode body = json.createObjectNode();
         body.put("templateID", templateId);
         body.put("timeout", timeoutSeconds);
         if (envVars != null && !envVars.isEmpty()) {
             ObjectNode envs = body.putObject("envVars");
             envVars.forEach(envs::put);
         }
+        if (mounts != null && !mounts.isEmpty()) {
+            var arr = body.putArray("volumeMounts");
+            int count = 0;
+            for (E2bVolumeMount m : mounts) {
+                if (m == null) {
+                    continue;
+                }
+                var o = arr.addObject();
+                o.put("name", m.getName());
+                o.put("path", m.getPath());
+                count++;
+            }
+            if (count == 0) {
+                body.remove("volumeMounts");
+            }
+        }
         String url = trimSlash(opt.getApiBaseUrl()) + "/sandboxes";
         return E2bRetry.withRetries(
                 opt.getMaxRetries(), () -> postJson(url, body, /* apiKey */ true));
 
@@ -27,6 +27,7 @@
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
 import java.io.InputStream;
+import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
@@ -142,9 +143,26 @@ protected ExecResult doExec(RuntimeContext runtimeContext, String command, int t
         return envd().runShell(e2bState, getWorkspaceRoot(), command, timeoutSeconds);
     }
 
+    @Override
+    protected boolean probeWorkspaceRootForPreservedResume() {
+        if (e2bState.isWorkspaceOnVolume()) {
+            // Files live on a persistent volume — the directory is durable across sandbox
+            // recreations, so treat it as preserved without probing.
+            return true;
+        }
+        return super.probeWorkspaceRootForPreservedResume();
+    }
+
     @Override
     protected InputStream doPersistWorkspace() throws Exception {
         if (e2bState.getPersistenceMode() == E2bPersistenceMode.NATIVE_SNAPSHOT) {
+            // Native snapshots preserve the software environment (installed deps, system state);
+            // volume bytes stay durable via the volume itself and mounts are re-attached on
+            // restore. Keep the snapshot call even when the workspace sits on a volume.
+            // Verified live
+            // (E2bVolumeMountLiveTest#nestedMountContentSurvivesNativeSnapshotRestoreUnchanged):
+            // platform snapshots do not capture mounted volume bytes, so a nested mount under a
+            // non-volume workspace root is unaffected by snapshot restore.
             JsonNode snap = platform.createSandboxSnapshot(e2bState.getSandboxId(), snapshotName());
             String id = snap.path("snapshotID").asText("");
             if (id.isBlank()) {
@@ -156,6 +174,13 @@ protected InputStream doPersistWorkspace() throws Exception {
             e2bState.getSnapshotIds().add(id);
             return new ByteArrayInputStream(E2bSnapshotRefs.encodeSnapshotId(id));
         }
+        if (e2bState.isWorkspaceOnVolume()) {
+            // Workspace bytes are durable via the volume — nothing to archive. The empty stream
+            // doubles as the no-op marker read back by doHydrateWorkspace: a session flipping
+            // between volume-backed and plain persistence replaces a real archive with this
+            // empty one, meaning "hydrate nothing, the volume already holds the files".
+            return InputStream.nullInputStream();
+        }
         String root = e2bState.getWorkspaceRoot();
         String tarPath = newTempTarPath();
         String script = buildTarCommand(true, tarPath, root);
@@ -183,6 +208,12 @@ protected Optional<InputStream> openSnapshotArchive(SandboxSnapshot snapshot) th
     @Override
     protected void doHydrateWorkspace(InputStream archive) throws Exception {
         byte[] all = archive.readAllBytes();
+        if (all.length == 0) {
+            // Volume-backed workspaces persist nothing to hydrate (see doPersistWorkspace); the
+            // empty archive is an intentional no-op marker, not an error, and must not overwrite
+            // what a previous non-volume archive contained.
+            return;
+        }
         String nativeId = E2bSnapshotRefs.decodeSnapshotIdIfPresent(all);
         if (nativeId != null && !nativeId.isBlank()) {
             restoreSandboxFromSnapshotTemplate(nativeId, all);
@@ -201,24 +232,23 @@ protected void doHydrateWorkspace(InputStream archive) throws Exception {
 
     @Override
     protected void doSetupWorkspace() throws Exception {
+        // mkdir's own cwd must already exist: a workspace root on a freshly mounted volume
+        // (e.g. /mnt/data/ws) typically does not exist yet, so run from / instead. The
+        // mkdir target is absolute and unaffected by the cwd.
         envd().runShell(
                         e2bState,
-                        getWorkspaceRoot(),
+                        "/",
                         "mkdir -p " + shellSingleQuote(e2bState.getWorkspaceRoot()),
                         30);
     }
 
     @Override
     protected void doDestroyWorkspace() throws Exception {
-        try {
-            envd().runShell(
-                            e2bState,
-                            getWorkspaceRoot(),
-                            "rm -rf " + shellSingleQuote(e2bState.getWorkspaceRoot()),
-                            30);
-        } catch (Exception e) {
-            log.debug("[sandbox-e2b] destroy workspace best-effort: {}", e.getMessage());
-        }
+        // No-op by contract. An E2B workspace's lifetime is bounded by the sandbox itself, so
+        // destruction is delegated to sandbox teardown; running "rm -rf" here beforehand would
+        // stretch a deletion through any nested volume mount into shared, persistent data
+        // without ever having an observable effect (the disk vanishes with the sandbox).
+        log.debug("[sandbox-e2b] workspace destruction is a no-op; sandbox teardown releases it");
     }
 
     @Override
@@ -314,6 +344,7 @@ private JsonNode createSandboxForRestore() throws IOException {
                     platform.createSandbox(
                             e2bState.getTemplateId(),
                             opt.getSandboxTimeoutSeconds(),
+                            e2bState.getVolumeMounts(),
                             resolveEnvVars());
             markWorkspaceUnready();
             return created;
@@ -336,6 +367,7 @@ private JsonNode createSandboxForRestore() throws IOException {
                         platform.createSandbox(
                                 e2bState.getTemplateId(),
                                 opt.getSandboxTimeoutSeconds(),
+                                e2bState.getVolumeMounts(),
                                 resolveEnvVars());
                 markWorkspaceUnready();
                 return created;
@@ -349,7 +381,10 @@ private JsonNode createSandboxForRestore() throws IOException {
         nativeSnapshotPlan = NativeSnapshotPlan.DEFAULT;
         JsonNode created =
                 platform.createSandbox(
-                        e2bState.getTemplateId(), opt.getSandboxTimeoutSeconds(), resolveEnvVars());
+                        e2bState.getTemplateId(),
+                        opt.getSandboxTimeoutSeconds(),
+                        e2bState.getVolumeMounts(),
+                        resolveEnvVars());
         markWorkspaceUnready();
         return created;
     }
@@ -370,7 +405,10 @@ private void markWorkspaceUnready() {
     private JsonNode createFromSnapshot(String snapshotId, byte[] archive) throws IOException {
         JsonNode created =
                 platform.createSandbox(
-                        snapshotId, opt.getSandboxTimeoutSeconds(), resolveEnvVars());
+                        snapshotId,
+                        opt.getSandboxTimeoutSeconds(),
+                        e2bState.getVolumeMounts(),
+                        resolveEnvVars());
         nativeSnapshotPlan = NativeSnapshotPlan.restored(snapshotId, archive);
         return created;
     }
@@ -493,6 +531,23 @@ private static String snapshotName() {
         return "agentscope-" + shortId + "-" + System.currentTimeMillis();
     }
 
+    /**
+     * {@code tar --exclude} args for volume mounts nested strictly beneath the workspace root.
+     * A mount covering the root needs no exclusion (persistence is a no-op in that case).
+     */
+    private List<String> volumeTarExcludeArgs() {
+        List<E2bVolumeMount> mounts = e2bState.getVolumeMounts();
+        if (mounts.isEmpty()) {
+            return List.of();
+        }
+        List<String> paths = new ArrayList<>(mounts.size());
+        for (E2bVolumeMount m : mounts) {
+            paths.add(m.getPath());
+        }
+        return WorkspaceMountSupport.tarExcludeArgsForAbsolutePaths(
+                e2bState.getWorkspaceRoot(), paths);
+    }
+
     private E2bEnvdProcessClient envd() throws Exception {
         E2bEnvdProcessClient c = envd;
         if (c == null) {
@@ -522,7 +577,16 @@ private String buildTarCommand(boolean create, String tarPath, String root) {
         StringBuilder script = new StringBuilder("tar ");
         for (String ex :
                 WorkspaceMountSupport.tarExcludeArgsForBindMounts(e2bState.getWorkspaceSpec())) {
-            script.append(ex).append(' ');
+            // Quote: exclude args derive from user-configured paths and may contain spaces.
+            script.append(shellSingleQuote(ex)).append(' ');
+        }
+        // Apply volume-mount excludes on both branches. The create branch must not re-duplicate
+        // volume bytes into the archive; the extract branch must not let archive entries that
+        // predate the current mount configuration (e.g. a NATIVE_SNAPSHOT archive written before
+        // the volume was mounted under the workspace root) write through the mount point into
+        // the shared volume.
+        for (String ex : volumeTarExcludeArgs()) {
+            script.append(shellSingleQuote(ex)).append(' ');
         }
         script.append(create ? "-cf " : "-xf ")
                 .append(tarPath)
@@ -551,10 +615,7 @@ private String workspaceTransferPath(String path) {
         if (root == null || root.isBlank() || !root.startsWith("/")) {
             return null;
         }
-        String normalizedRoot = root.replace('\\', '/');
-        while (normalizedRoot.length() > 1 && normalizedRoot.endsWith("/")) {
-            normalizedRoot = normalizedRoot.substring(0, normalizedRoot.length() - 1);
-        }
+        String normalizedRoot = WorkspaceMountSupport.normalizeVirtualPath(root);
         String rootPrefix = "/".equals(normalizedRoot) ? "/" : normalizedRoot + "/";
         if (!path.startsWith(rootPrefix)) {
             return null;
 
@@ -58,6 +58,7 @@ public Sandbox create(
             E2bSandboxClientOptions options) {
         String sessionId = UUID.randomUUID().toString();
         E2bSandboxClientOptions merged = merge(options);
+        requireAbsoluteWorkspaceRoot(merged.getWorkspaceRoot());
 
         E2bSandboxState state = new E2bSandboxState();
         state.setSessionId(sessionId);
@@ -70,6 +71,8 @@ public Sandbox create(
         state.setCodec(merged.getCodec());
         state.setSandboxDomain(merged.getDomain());
         state.setEnvdSandboxUrl(merged.getEnvdSandboxUrl());
+        state.setVolumeMounts(merged.getVolumeMounts());
+        state.setWorkspaceOnVolume(isWorkspaceOnVolume(merged));
 
         if (snapshotSpec != null) {
             state.setSnapshot(snapshotSpec.build(sessionId));
@@ -85,6 +88,7 @@ public Sandbox resume(SandboxState state) {
             throw new IllegalArgumentException(
                     "Expected E2bSandboxState but got: " + state.getClass().getName());
         }
+        requireAbsoluteWorkspaceRoot(e2b.getWorkspaceRoot());
         E2bSandboxClientOptions resumed = copy(defaultOptions);
         resumed.setCodec(e2b.getCodec());
         resumed.setEnvdSandboxUrl(e2b.getEnvdSandboxUrl());
@@ -152,6 +156,11 @@ private E2bSandboxClientOptions merge(E2bSandboxClientOptions call) {
         if (call.getHttpClient() != null) {
             o.setHttpClient(call.getHttpClient());
         }
+        // Null or empty call mounts keep the defaults (same convention as AgentRun OSS mounts);
+        // there is intentionally no "clear all mounts" via merge.
+        if (call.getVolumeMounts() != null && !call.getVolumeMounts().isEmpty()) {
+            o.setVolumeMounts(call.getVolumeMounts());
+        }
         o.setConnectTimeoutSeconds(call.getConnectTimeoutSeconds());
         o.setReadTimeoutSeconds(call.getReadTimeoutSeconds());
         o.setMaxRetries(call.getMaxRetries());
@@ -166,6 +175,41 @@ private E2bSandboxClientOptions merge(E2bSandboxClientOptions call) {
         return o;
     }
 
+    /**
+     * Rejects blank or relative workspace roots fail-fast; every E2B operation assumes an
+     * absolute in-sandbox path.
+     *
+     * @param workspaceRoot workspace root to check
+     */
+    private static void requireAbsoluteWorkspaceRoot(String workspaceRoot) {
+        if (workspaceRoot == null
+                || workspaceRoot.isBlank()
+                || !workspaceRoot.strip().startsWith("/")) {
+            throw new SandboxException.SandboxConfigurationException(
+                    "E2B workspaceRoot must be an absolute in-sandbox path but was: "
+                            + workspaceRoot);
+        }
+    }
+
+    /**
+     * Returns whether the workspace root lives on one of the configured volume mounts.
+     *
+     * @param opt merged client options
+     * @return true when a mount covers the workspace root
+     */
+    private static boolean isWorkspaceOnVolume(E2bSandboxClientOptions opt) {
+        String root = opt.getWorkspaceRoot();
+        if (root == null || root.isBlank() || opt.getVolumeMounts() == null) {
+            return false;
+        }
+        for (E2bVolumeMount m : opt.getVolumeMounts()) {
+            if (m != null && E2bVolumeMount.coversWorkspaceRoot(root, m.getPath())) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     private static E2bSandboxClientOptions copy(E2bSandboxClientOptions src) {
         E2bSandboxClientOptions o = new E2bSandboxClientOptions();
         o.setApiKey(src.getApiKey());
@@ -179,6 +223,7 @@ private static E2bSandboxClientOptions copy(E2bSandboxClientOptions src) {
         o.setPersistenceMode(src.getPersistenceMode());
         o.setCodec(src.getCodec());
         o.setHttpClient(src.getHttpClient());
+        o.setVolumeMounts(src.getVolumeMounts());
         o.setConnectTimeoutSeconds(src.getConnectTimeoutSeconds());
         o.setReadTimeoutSeconds(src.getReadTimeoutSeconds());
         o.setMaxRetries(src.getMaxRetries());