Skip to content

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.go
index 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.go
index 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.go
index 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 isolation
import (
+ "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.go
new file mode 100644
index 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.go
index 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 in
diff --git a/docs/guides/isolation-sessions.md b/docs/guides/isolation-sessions.md
index 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.ts
index 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.py
index 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 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`.
+ 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 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`.
+ 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 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`.
+ 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 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`.
+ 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.py
index 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 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.
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.py
index 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 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).
+ 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.yaml
index 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 be
provided, 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 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).
+ 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:
- path
properties: