Secure, Fast, and Extensible Sandbox runtime for AI agents.
fix(execd): reject out-of-scope absolute paths in the session files view
高然c7a3998b7088
diff --git a/components/execd/pkg/isolation/merged_view.go b/components/execd/pkg/isolation/merged_view.goindex 54c602717..281c7ef43 100644--- a/components/execd/pkg/isolation/merged_view.go+++ b/components/execd/pkg/isolation/merged_view.go@@ -66,15 +66,24 @@ func (m *MergedView) resolveLower(rel string) string {}// safePath validates and returns a path relative to the workspace.-// Absolute paths under LowerDir are stripped to relative; all others-// are cleaned normally.+// Relative paths are cleaned; absolute paths must fall under LowerDir and+// are stripped to relative — anything else is rejected with+// ErrPathOutsideOverlays instead of being silently resolved against the+// workspace, where it would touch a different file than the namespace path+// refers to (bind destinations, the profile's private /tmp, etc.).+// A LowerDir of "/" is the namespace root and contains every absolute path.func (m *MergedView) safePath(path string) (string, error) {cleaned := filepath.Clean(path)- // Strip workspace prefix from absolute paths so Join works correctly.- if m.LowerDir != "" && strings.HasPrefix(cleaned, m.LowerDir+"/") {- cleaned = strings.TrimPrefix(cleaned, m.LowerDir+"/")- } else if m.LowerDir != "" && cleaned == m.LowerDir {- cleaned = "."+ if filepath.IsAbs(cleaned) {+ if m.LowerDir != "/" &&+ (m.LowerDir == "" ||+ (cleaned != m.LowerDir && !strings.HasPrefix(cleaned, m.LowerDir+"/"))) {+ return "", fmt.Errorf("%w: %s", ErrPathOutsideOverlays, path)+ }+ if cleaned == m.LowerDir {+ return ".", nil+ }+ return strings.TrimPrefix(cleaned, m.LowerDir+"/"), nil}if strings.HasPrefix(cleaned, "..") {return "", fmt.Errorf("path traversal denied: %s", path)diff --git a/components/execd/pkg/isolation/merged_view_router_test.go b/components/execd/pkg/isolation/merged_view_router_test.goindex 1fcd21098..b24dce48f 100644--- a/components/execd/pkg/isolation/merged_view_router_test.go+++ b/components/execd/pkg/isolation/merged_view_router_test.go@@ -34,7 +34,10 @@ import (func newRouterFixture(t *testing.T) (*MultiMergedView, string) {t.Helper()- base := t.TempDir()+ // Resolve symlinks: MergedView rejects symlinked path components, and+ // t.TempDir() sits under the /var symlink on macOS.+ base, err := filepath.EvalSymlinks(t.TempDir())+ require.NoError(t, err)wsLower := filepath.Join(base, "ws")wsUpper := filepath.Join(base, "upper-ws")subLower := filepath.Join(wsLower, "sub")@@ -132,7 +135,8 @@ func TestMultiMergedView_LongestPrefixRouting(t *testing.T) {}func TestMultiMergedView_ModeSemanticsPreserved(t *testing.T) {- base := t.TempDir()+ base, err := filepath.EvalSymlinks(t.TempDir())+ require.NoError(t, err)roLower := filepath.Join(base, "ro")roUpper := filepath.Join(base, "upper-ro")require.NoError(t, os.MkdirAll(roLower, 0o755))diff --git a/components/execd/pkg/isolation/merged_view_test.go b/components/execd/pkg/isolation/merged_view_test.goindex 4d4b76068..a3fd19a4b 100644--- a/components/execd/pkg/isolation/merged_view_test.go+++ b/components/execd/pkg/isolation/merged_view_test.go@@ -15,6 +15,7 @@package isolationimport (+ "errors""os""path/filepath""strings"@@ -26,10 +27,19 @@ import (func newTestMergedView(t *testing.T, mode WorkspaceMode) *MergedView {t.Helper()+ // Resolve symlinks: MergedView rejects symlinked path components, and+ // t.TempDir() sits under the /var symlink on macOS.lower := filepath.Join(t.TempDir(), "lower")upper := filepath.Join(t.TempDir(), "upper")require.NoError(t, os.MkdirAll(lower, 0o755))require.NoError(t, os.MkdirAll(upper, 0o755))+ var err error+ if lower, err = filepath.EvalSymlinks(lower); err != nil {+ t.Fatal(err)+ }+ if upper, err = filepath.EvalSymlinks(upper); err != nil {+ t.Fatal(err)+ }return NewMergedView(lower, upper, mode, uint32(os.Getuid()), uint32(os.Getgid()))}@@ -255,3 +265,94 @@ func TestMergedView_ReadOnly_AllWritesDenied(t *testing.T) {assert.Error(t, mv.Rename("a", "b"))assert.Error(t, mv.Chmod("x.txt", 0o755))}++func TestMergedView_AbsolutePathOutsideLowerRejected(t *testing.T) {+ mv := newTestMergedView(t, WorkspaceOverlay)++ // Every operation rejects an absolute path outside LowerDir instead of+ // silently resolving it against the workspace.+ outside := []string{"/tmp/escape.txt", "/etc/passwd", "/etc", "/"}+ for _, p := range outside {+ _, err := mv.Stat(p)+ assert.True(t, errors.Is(err, ErrPathOutsideOverlays), "Stat %s = %v", p, err)++ _, err = mv.ReadFile(p)+ assert.True(t, errors.Is(err, ErrPathOutsideOverlays), "ReadFile %s = %v", p, err)++ _, err = mv.Open(p)+ assert.True(t, errors.Is(err, ErrPathOutsideOverlays), "Open %s = %v", p, err)++ _, err = mv.ReadDir(p)+ assert.True(t, errors.Is(err, ErrPathOutsideOverlays), "ReadDir %s = %v", p, err)++ assert.True(t, errors.Is(mv.WriteFile(p, []byte("x"), 0o644), ErrPathOutsideOverlays), "WriteFile %s", p)+ assert.True(t, errors.Is(mv.MkdirAll(p, 0o755), ErrPathOutsideOverlays), "MkdirAll %s", p)+ assert.True(t, errors.Is(mv.Remove(p), ErrPathOutsideOverlays), "Remove %s", p)+ assert.True(t, errors.Is(mv.RemoveAll(p), ErrPathOutsideOverlays), "RemoveAll %s", p)+ assert.True(t, errors.Is(mv.Chmod(p, 0o644), ErrPathOutsideOverlays), "Chmod %s", p)+ assert.True(t, errors.Is(mv.ReplaceContent(p, "a", "b"), ErrPathOutsideOverlays), "ReplaceContent %s", p)+ }+ _, err := mv.Search("/tmp", "*")+ assert.True(t, errors.Is(err, ErrPathOutsideOverlays), "Search /tmp = %v", err)+ assert.True(t, errors.Is(mv.Rename("a.txt", "/tmp/b.txt"), ErrPathOutsideOverlays), "Rename to /tmp/b.txt")+ assert.True(t, errors.Is(mv.Rename("/tmp/a.txt", "b.txt"), ErrPathOutsideOverlays), "Rename from /tmp/a.txt")++ // Nothing leaked into the upper directory.+ entries, err := os.ReadDir(mv.UpperDir)+ require.NoError(t, err)+ assert.Empty(t, entries, "rejected paths must not land in the upper dir")+}++func TestMergedView_AbsolutePathUnderLowerStillWorks(t *testing.T) {+ mv := newTestMergedView(t, WorkspaceOverlay)+ require.NoError(t, os.WriteFile(filepath.Join(mv.LowerDir, "ws.txt"), []byte("lower"), 0o644))++ // Absolute path under LowerDir is stripped and served normally.+ info, err := mv.Stat(filepath.Join(mv.LowerDir, "ws.txt"))+ require.NoError(t, err)+ assert.Equal(t, "ws.txt", info.Name())++ require.NoError(t, mv.WriteFile(filepath.Join(mv.LowerDir, "abs.txt"), []byte("via-abs"), 0o644))+ data, err := os.ReadFile(filepath.Join(mv.UpperDir, "abs.txt"))+ require.NoError(t, err)+ assert.Equal(t, "via-abs", string(data))++ require.NoError(t, mv.Remove(filepath.Join(mv.LowerDir, "abs.txt")))+ _, err = os.Stat(filepath.Join(mv.UpperDir, "abs.txt"))+ assert.True(t, os.IsNotExist(err))+}++func TestMergedView_RootLowerServesAllAbsolutePaths(t *testing.T) {+ // A "/" overlay is the namespace root: every absolute path belongs to it.+ upper := filepath.Join(t.TempDir(), "upper")+ require.NoError(t, os.MkdirAll(upper, 0o755))+ upper, err := filepath.EvalSymlinks(upper)+ require.NoError(t, err)+ mv := NewMergedView("/", upper, WorkspaceOverlay, 0, 0)++ _, statErr := mv.Stat("/definitely-not-a-real-path-87953550")+ assert.False(t, errors.Is(statErr, ErrPathOutsideOverlays), "root view must not reject absolute paths")+ assert.True(t, os.IsNotExist(statErr))+}++func TestMergedView_EmptyLowerRejectsAbsolutePaths(t *testing.T) {+ // Defensive: a view without a lower root has no namespace scope to+ // resolve absolute paths against.+ mv := NewMergedView("", t.TempDir(), WorkspaceOverlay, 0, 0)++ _, err := mv.Stat("/tmp/x")+ assert.True(t, errors.Is(err, ErrPathOutsideOverlays))+}++func TestMergedView_TraversalDenialUnchanged(t *testing.T) {+ mv := newTestMergedView(t, WorkspaceRW)++ _, err := mv.Stat("../etc/passwd")+ assert.Error(t, err)+ assert.Contains(t, err.Error(), "traversal")++ // A path that escapes LowerDir via .. cleans to an absolute path+ // outside the workspace and is rejected as out-of-scope.+ _, err = mv.Stat(filepath.Join(mv.LowerDir, "..", "etc", "passwd"))+ assert.True(t, errors.Is(err, ErrPathOutsideOverlays))+}diff --git a/components/execd/pkg/runtime/bwrap_test/bwrap_single_overlay_files_test.go b/components/execd/pkg/runtime/bwrap_test/bwrap_single_overlay_files_test.gonew file mode 100644index 000000000..e658f794d--- /dev/null+++ b/components/execd/pkg/runtime/bwrap_test/bwrap_single_overlay_files_test.go@@ -0,0 +1,76 @@+// Copyright 2026 The OpenSandbox Authors+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++//go:build linux && bwrap++package bwrap_test++import (+ "errors"+ "os"+ "path/filepath"+ "testing"++ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"++ "github.com/alibaba/opensandbox/execd/pkg/isolation"+ "github.com/alibaba/opensandbox/execd/pkg/runtime"+)++// TestSingleOverlayFiles_PathOutsideWorkspaceRejected pins the default+// single-overlay session shape: absolute paths outside the workspace (the+// shared /tmp, /etc, ...) are rejected with ErrPathOutsideOverlays instead+// of silently resolving against the workspace upper, where they would touch+// a different file than the namespace path refers to. session.run keeps+// full namespace access; the files API serves exactly the session mounts.+func TestSingleOverlayFiles_PathOutsideWorkspaceRejected(t *testing.T) {+ r := newRunner(t)++ wsDir := "/tmp/bwrap-test-single-overlay-files"+ require.NoError(t, os.MkdirAll(wsDir, 0o755))+ defer os.RemoveAll(wsDir)++ opts := &runtime.IsolatedSessionOptions{+ Profile: "balanced", WorkspacePath: wsDir, WorkspaceMode: "overlay",+ }+ id, err := r.CreateIsolatedSession(opts)+ require.NoError(t, err)+ t.Cleanup(func() { _ = r.DeleteIsolatedSession(id) })++ // The run direction works and can write both the workspace and /tmp.+ escaped := "/tmp/single-overlay-escape.txt"+ runInSession(t, r, id,+ "echo run-data > "+filepath.Join(wsDir, "run.txt")+" && echo ns-data > "+escaped, nil)++ // Out-of-scope absolute paths are rejected, not silently joined into+ // the workspace upper.+ mv, err := r.GetMergedView(id)+ require.NoError(t, err)+ for _, p := range []string{escaped, "/etc/passwd"} {+ _, err := mv.ReadFile(p)+ require.Error(t, err)+ assert.True(t, errors.Is(err, isolation.ErrPathOutsideOverlays), "ReadFile %s = %v", p, err)+ }+ require.Error(t, mv.WriteFile(escaped, []byte("x"), 0o644))++ // The rejected write never landed in the workspace upper.+ _, err = os.Stat(filepath.Join(wsDir, "tmp", filepath.Base(escaped)))+ assert.True(t, os.IsNotExist(err), "rejected write leaked into the workspace upper")++ // Run→API direction on the workspace itself still works.+ data, err := mv.ReadFile(filepath.Join(wsDir, "run.txt"))+ require.NoError(t, err)+ assert.Equal(t, "run-data\n", string(data))+}diff --git a/components/execd/pkg/runtime/isolated_session_binds_view_test.go b/components/execd/pkg/runtime/isolated_session_binds_view_test.goindex a334f1bc2..430660ecd 100644--- a/components/execd/pkg/runtime/isolated_session_binds_view_test.go+++ b/components/execd/pkg/runtime/isolated_session_binds_view_test.go@@ -322,6 +322,70 @@ func TestNewMergedView_BindsWithoutOverlaysDoesNotPanic(t *testing.T) {}}+// TestNewMergedView_SingleOverlayRejectsPathsOutsideWorkspace pins the+// single-overlay, no-binds session shape: the historical bare MergedView is+// preserved, but absolute paths outside the workspace (bind-like+// destinations, the strict profile's private /tmp) must be rejected with+// ErrPathOutsideOverlays instead of silently resolving against the+// workspace upper, where they would touch a different file than the+// namespace path refers to.+func TestNewMergedView_SingleOverlayRejectsPathsOutsideWorkspace(t *testing.T) {+ base, err := filepath.EvalSymlinks(t.TempDir())+ if err != nil {+ t.Fatal(err)+ }+ wsLower := filepath.Join(base, "ws")+ wsUpper := filepath.Join(base, "upper-ws")+ for _, dir := range []string{wsLower, wsUpper} {+ if err := os.MkdirAll(dir, 0o755); err != nil {+ t.Fatal(err)+ }+ }++ persist := true+ s := newBindsViewSession(t,+ []IsolatedOverlayOptions{{Path: wsLower, Mode: "overlay", Persist: &persist}},+ map[int]string{0: wsUpper},+ nil,+ )+ view := newMergedView(s)+ if _, ok := view.(*isolation.MergedView); !ok {+ t.Fatalf("view type %T, want *isolation.MergedView for the single-overlay shape", view)+ }++ for _, p := range []string{"/tmp/secret.txt", "/etc/hostname", "/mnt/skills/a.txt"} {+ if _, err := view.Stat(p); !errors.Is(err, isolation.ErrPathOutsideOverlays) {+ t.Errorf("Stat %s = %v, want ErrPathOutsideOverlays", p, err)+ }+ if err := view.WriteFile(p, []byte("x"), 0o644); !errors.Is(err, isolation.ErrPathOutsideOverlays) {+ t.Errorf("WriteFile %s = %v, want ErrPathOutsideOverlays", p, err)+ }+ }++ // Nothing leaked into the workspace upper.+ if _, err := os.Stat(filepath.Join(wsUpper, "tmp")); !os.IsNotExist(err) {+ t.Errorf("rejected write leaked into workspace upper: %v", err)+ }++ // Workspace-scoped access keeps working.+ if err := os.WriteFile(filepath.Join(wsLower, "seed.txt"), []byte("seed"), 0o644); err != nil {+ t.Fatal(err)+ }+ if _, err := view.Stat(filepath.Join(wsLower, "seed.txt")); err != nil {+ t.Errorf("Stat under workspace = %v, want nil", err)+ }+ data, err := view.ReadFile("seed.txt")+ if err != nil || string(data) != "seed" {+ t.Errorf("relative read = (%q, %v), want (\"seed\", nil)", data, err)+ }+ if err := view.WriteFile(filepath.Join(wsLower, "from-api.txt"), []byte("x"), 0o644); err != nil {+ t.Fatalf("workspace write = %v, want nil", err)+ }+ if _, err := os.Stat(filepath.Join(wsUpper, "from-api.txt")); err != nil {+ t.Fatalf("workspace write missing in upper: %v", err)+ }+}+// TestValidateBindMountStack pins the mount-stack collisions the files view// cannot represent: duplicates, ancestor binds, and trusted-base shadowing.// Bind == overlay/extra_writable dest is allowed (the later bind shadows indiff --git a/docs/guides/isolation-sessions.md b/docs/guides/isolation-sessions.mdindex f0e353bb1..340118088 100644--- a/docs/guides/isolation-sessions.md+++ b/docs/guides/isolation-sessions.md@@ -252,6 +252,10 @@ Background run semantics:Overlay upper dirs live under `upper_root` (default `/var/lib/execd/isolation`).+::: warning Overlay mode is one-directional for the files API+While a session is running, files-API writes on an `overlay` workspace land in the host upper directory and are **not visible to `session.run`**: the kernel caches the overlayfs directory entries at mount time, so host-side writes bypass the overlay the namespace already holds. The `session.run` → `session.files` direction always works. For bidirectional file exchange between the two views, use workspace `mode: "rw"` or a bind mount instead of `overlay`.+:::+Because isolated-session state lives only in execd's memory, every session left under `upper_root` when execd exits is stale. Before publishing a new session, execd creates a durable cleanup record at `<upper_root>/.execd-cleanup/<session-id>`; on startup it recovers those records and removes the exact matching session directories. A record is retired only after the entire session subtree has been deleted, so partial deletion and transient filesystem failure retain a retryable identity across restarts. Residue that cannot be removed yet — e.g. an upper still referenced by a mount from the previous lifetime — stays counted toward `upper_max_bytes` and is retried by the idle collector.Only recorded session directories are removed. Unrecorded children under `upper_root`, including allocator-shaped directory trees, are treated as operator data and are never reclaimed automatically. Directories left by execd versions that predate the cleanup registry therefore require explicit migration or manual cleanup; keep `upper_root` dedicated to execd and do not modify the reserved `.execd-cleanup` registry. In pooled / pre-provisioned sandboxes this prevents one occupant's session data from leaking to the next.@@ -279,7 +283,7 @@ A session can carry **several independent overlay mounts** via the `overlays` re- Each entry has its own mount semantics, so workspace files, system-level changes (`apt install` → `/usr`, config → `/etc`), and additional project directories get **independent copy-on-write uppers**.- Mounts are applied shallow-first; a nested overlay (e.g. `/workspace` on top of a `/` root overlay) shadows its ancestors within its own subtree. Paths must be absolute and unique.- `persist` (overlay mode only, default `true`): `true` allocates a host upper directory under `upper_root`; `false` uses an ephemeral tmpfs upper whose writes are discarded when the session ends. `rw`/`ro` entries must not set `persist`. An ephemeral upper lives inside the namespace only, so the files API serves `persist=false` overlays from their host-side content: in-session writes under such an overlay are not observable through the files API and files-API writes into it are rejected.-- The files API routes each request to the session mount (overlay or bind) whose mount path is the longest prefix of the requested path; relative paths resolve against the first overlay.+- The files API routes each request to the session mount (overlay or bind) whose mount path is the longest prefix of the requested path; relative paths resolve against the first overlay. Paths outside every session mount — a `binds` destination that was not configured, a strict profile's private `/tmp`, `/etc`, ... — are rejected with an error instead of being silently resolved against the workspace.- Background runs use the **first** overlay for their log location: it must be `rw`, or `overlay` with `persist: true`; otherwise background runs are rejected.---@@ -340,7 +344,7 @@ Private Sessions are not recoverable across an execd restart. Deployments that e## Filesystem Proxy-Reads and writes the session's **merged** mount view — the workspace overlays plus every `binds` destination — from outside the namespace. This is how SDKs `upload`, `download`, and `list` without spawning a shell, including against bind-mounted persistent data. All paths are per session under `/v1/isolated/session/{id}/`:+Reads and writes the session's **merged** mount view — the workspace overlays plus every `binds` destination — from outside the namespace. This is how SDKs `upload`, `download`, and `list` without spawning a shell, including against bind-mounted persistent data. The files API serves exactly those session mounts: absolute paths outside every mount (namespace-only locations such as a strict profile's private `/tmp`, or unconfigured `binds` destinations) are rejected with an error rather than resolving to a different file. All paths are per session under `/v1/isolated/session/{id}/`:| Method | Path ||---|---|@@ -356,7 +360,7 @@ Reads and writes the session's **merged** mount view — the workspace overlays| `POST` | `directories` || `DELETE` | `directories?path=...` |-Writes on a `ro` workspace fail; writes on `overlay` land in the upper dir and vanish on `DELETE`; writes on a `readonly` bind fail.+Writes on a `ro` workspace fail; writes on `overlay` land in the upper dir and vanish on `DELETE`, and while the session runs they are not visible to `session.run` (see [Workspace Modes](#workspace-modes)); writes on a `readonly` bind fail.---diff --git a/sdks/sandbox/javascript/src/api/execd.ts b/sdks/sandbox/javascript/src/api/execd.tsindex 53f9d3df7..29e12d6b0 100644--- a/sdks/sandbox/javascript/src/api/execd.ts+++ b/sdks/sandbox/javascript/src/api/execd.ts@@ -1,11 +1,11 @@// Copyright 2026 The OpenSandbox Authors-//+//// Licensed under the Apache License, Version 2.0 (the "License");// you may not use this file except in compliance with the License.// You may obtain a copy of the License at-//+//// http://www.apache.org/licenses/LICENSE-2.0-//+//// Unless required by applicable law or agreed to in writing, software// distributed under the License is distributed on an "AS IS" BASIS,// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.@@ -1642,7 +1642,7 @@ export interface components {*/message: string;};- /** @description Creates an isolated session with one or more overlay mounts. The legacy `workspace` field is kept as sugar for a single-element `overlays` list: at least one of `workspace` or `overlays` must be provided, and when both are present `workspace` is prepended to `overlays`. */+ /** @description Creates an isolated session with one or more overlay mounts. The legacy `workspace` field is kept as sugar for a single-element `overlays` list: at least one of `workspace` or `overlays` must be provided, and when both are present `workspace` is prepended to `overlays`. The session files API serves exactly the session mounts (overlays, extra_writable, binds): paths under each mount resolve as the namespace sees them, and absolute paths outside every session mount are rejected instead of resolving against the workspace. */CreateIsolatedSessionRequest: {/** @enum {string} */profile?: "strict" | "balanced";@@ -1670,7 +1670,7 @@ export interface components {/** @enum {string} */mode?: "rw" | "overlay" | "ro";};- /** @description One overlay mount inside the isolated namespace. `mode=overlay` mounts a copy-on-write view: with `persist=true` (default) writes land in a host upper directory tracked and usage-accounted by execd (the substrate for the diff/commit endpoints); with `persist=false` the upper is an ephemeral tmpfs whose writes are discarded when the session ends. `rw` and `ro` bind the host path directly; `persist` applies to overlay mode only and must be omitted for them (execd rejects the request otherwise). */+ /** @description One overlay mount inside the isolated namespace. `mode=overlay` mounts a copy-on-write view: with `persist=true` (default) writes land in a host upper directory tracked and usage-accounted by execd (the substrate for the diff/commit endpoints); with `persist=false` the upper is an ephemeral tmpfs whose writes are discarded when the session ends. `rw` and `ro` bind the host path directly; `persist` applies to overlay mode only and must be omitted for them (execd rejects the request otherwise). Overlay mode is one-directional for the session files API: while the session runs, files-API writes land in the host upper directory and are not visible to runs inside the namespace (the kernel caches overlayfs directory entries at mount time), while the run-to-files direction works; use `rw` or `binds` for bidirectional file exchange. */IsolatedOverlaySpec: {/*** @description Mount destination inside the namespace (absolute).diff --git a/sdks/sandbox/python/src/opensandbox/api/execd/api/isolated_execution/create_isolated_session.py b/sdks/sandbox/python/src/opensandbox/api/execd/api/isolated_execution/create_isolated_session.pyindex 47c000063..c6fd0de43 100644--- a/sdks/sandbox/python/src/opensandbox/api/execd/api/isolated_execution/create_isolated_session.py+++ b/sdks/sandbox/python/src/opensandbox/api/execd/api/isolated_execution/create_isolated_session.py@@ -92,7 +92,10 @@ def sync_detailed(body (CreateIsolatedSessionRequest): Creates an isolated session with one or more overlaymounts. The legacy `workspace` field is kept as sugar for a single-element `overlays`list: at least one of `workspace` or `overlays` must be provided, and when both are- present `workspace` is prepended to `overlays`.+ present `workspace` is prepended to `overlays`. The session files API serves exactly the+ session mounts (overlays, extra_writable, binds): paths under each mount resolve as the+ namespace sees them, and absolute paths outside every session mount are rejected instead+ of resolving against the workspace.Raises:errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.@@ -124,7 +127,10 @@ def sync(body (CreateIsolatedSessionRequest): Creates an isolated session with one or more overlaymounts. The legacy `workspace` field is kept as sugar for a single-element `overlays`list: at least one of `workspace` or `overlays` must be provided, and when both are- present `workspace` is prepended to `overlays`.+ present `workspace` is prepended to `overlays`. The session files API serves exactly the+ session mounts (overlays, extra_writable, binds): paths under each mount resolve as the+ namespace sees them, and absolute paths outside every session mount are rejected instead+ of resolving against the workspace.Raises:errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.@@ -151,7 +157,10 @@ async def asyncio_detailed(body (CreateIsolatedSessionRequest): Creates an isolated session with one or more overlaymounts. The legacy `workspace` field is kept as sugar for a single-element `overlays`list: at least one of `workspace` or `overlays` must be provided, and when both are- present `workspace` is prepended to `overlays`.+ present `workspace` is prepended to `overlays`. The session files API serves exactly the+ session mounts (overlays, extra_writable, binds): paths under each mount resolve as the+ namespace sees them, and absolute paths outside every session mount are rejected instead+ of resolving against the workspace.Raises:errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.@@ -181,7 +190,10 @@ async def asyncio(body (CreateIsolatedSessionRequest): Creates an isolated session with one or more overlaymounts. The legacy `workspace` field is kept as sugar for a single-element `overlays`list: at least one of `workspace` or `overlays` must be provided, and when both are- present `workspace` is prepended to `overlays`.+ present `workspace` is prepended to `overlays`. The session files API serves exactly the+ session mounts (overlays, extra_writable, binds): paths under each mount resolve as the+ namespace sees them, and absolute paths outside every session mount are rejected instead+ of resolving against the workspace.Raises:errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.diff --git a/sdks/sandbox/python/src/opensandbox/api/execd/models/create_isolated_session_request.py b/sdks/sandbox/python/src/opensandbox/api/execd/models/create_isolated_session_request.pyindex f6c1eee0e..303d9059c 100644--- a/sdks/sandbox/python/src/opensandbox/api/execd/models/create_isolated_session_request.py+++ b/sdks/sandbox/python/src/opensandbox/api/execd/models/create_isolated_session_request.py@@ -40,7 +40,9 @@ T = TypeVar("T", bound="CreateIsolatedSessionRequest")class CreateIsolatedSessionRequest:"""Creates an isolated session with one or more overlay mounts. The legacy `workspace` field is kept as sugar for asingle-element `overlays` list: at least one of `workspace` or `overlays` must be provided, and when both are- present `workspace` is prepended to `overlays`.+ present `workspace` is prepended to `overlays`. The session files API serves exactly the session mounts (overlays,+ extra_writable, binds): paths under each mount resolve as the namespace sees them, and absolute paths outside every+ session mount are rejected instead of resolving against the workspace.Attributes:profile (CreateIsolatedSessionRequestProfile | Unset):diff --git a/sdks/sandbox/python/src/opensandbox/api/execd/models/isolated_overlay_spec.py b/sdks/sandbox/python/src/opensandbox/api/execd/models/isolated_overlay_spec.pyindex 3e773aace..a37d4bcbf 100644--- a/sdks/sandbox/python/src/opensandbox/api/execd/models/isolated_overlay_spec.py+++ b/sdks/sandbox/python/src/opensandbox/api/execd/models/isolated_overlay_spec.py@@ -34,7 +34,10 @@ class IsolatedOverlaySpec:(default) writes land in a host upper directory tracked and usage-accounted by execd (the substrate for thediff/commit endpoints); with `persist=false` the upper is an ephemeral tmpfs whose writes are discarded when thesession ends. `rw` and `ro` bind the host path directly; `persist` applies to overlay mode only and must be omitted- for them (execd rejects the request otherwise).+ for them (execd rejects the request otherwise). Overlay mode is one-directional for the session files API: while the+ session runs, files-API writes land in the host upper directory and are not visible to runs inside the namespace+ (the kernel caches overlayfs directory entries at mount time), while the run-to-files direction works; use `rw` or+ `binds` for bidirectional file exchange.Attributes:path (str): Mount destination inside the namespace (absolute). Example: /workspace.diff --git a/specs/execd-api.yaml b/specs/execd-api.yamlindex 8c4215d76..6a2409d2d 100644--- a/specs/execd-api.yaml+++ b/specs/execd-api.yaml@@ -2953,7 +2953,11 @@ components:legacy `workspace` field is kept as sugar for a single-element`overlays` list: at least one of `workspace` or `overlays` must beprovided, and when both are present `workspace` is prepended to- `overlays`.+ `overlays`. The session files API serves exactly the session mounts+ (overlays, extra_writable, binds): paths under each mount resolve+ as the namespace sees them, and absolute paths outside every+ session mount are rejected instead of resolving against the+ workspace.properties:profile:type: string@@ -3037,7 +3041,13 @@ components:`persist=false` the upper is an ephemeral tmpfs whose writes arediscarded when the session ends. `rw` and `ro` bind the host pathdirectly; `persist` applies to overlay mode only and must be- omitted for them (execd rejects the request otherwise).+ omitted for them (execd rejects the request otherwise). Overlay+ mode is one-directional for the session files API: while the+ session runs, files-API writes land in the host upper directory+ and are not visible to runs inside the namespace (the kernel+ caches overlayfs directory entries at mount time), while the+ run-to-files direction works; use `rw` or `binds` for+ bidirectional file exchange.required:- pathproperties: