[Sandbox] Add a run-scoped cwd across capabilities when reusing a live session #4401

Describe the feature

I would like to bind each SandboxAgent run to a logical working directory inside a developer-owned live sandbox, with consistent relative-path behavior across sandbox capabilities.

The SDK currently supports sharing one live sandbox session, but every run uses the session-wide Manifest.root for filesystem path resolution:

• exec_command(workdir=...) changes the directory for that shell command only.
• view_image("plot.png") resolves from the session workspace root.
• apply_patch paths are workspace-root-relative, not relative to the shell workdir.
• run_as changes the OS identity and permissions, but not path resolution.

This behavior is documented, so I am filing this as a feature request rather than a bug.

Relevant current behavior:

• exec_command implements workdir as a per-command cd
• view_image uses the session-wide workspace path policy
• SandboxRunConfig has no run-level cwd or workspace view
• The Sandbox Agents guide notes that apply_patch paths are relative to the workspace root rather than shell workdir.

Production use case

Our application runs several trusted document-research agents concurrently. They share the same dependencies and do not require separate containers or security-grade isolation. Each agent only needs a reliable task-local directory:

/workspace/tasks/task-a
/workspace/tasks/task-b

We originally reused one Modal sandbox and assigned each child a task directory. This produced two related problems:

1. Concurrent children sometimes chose identical workspace-root-relative filenames and overwrote or read each other's files.
2. After forcing each child's shell commands into its task directory, filesystem capabilities still used the session root.

For example:

exec_command(
    cmd="render input.pdf --output page.png",
    workdir="tasks/task-a",
)

view_image(path="page.png")
# Looks for /workspace/page.png rather than
# /workspace/tasks/task-a/page.png.

apply_patch(path="notes.md", ...)
# Edits /workspace/notes.md rather than
# /workspace/tasks/task-a/notes.md.

We worked around this with capability-specific path-prefixing adapters, task-local temporary directories, and prompt instructions. That remained brittle because every path-bearing capability or custom tool had to implement the convention independently.

We eventually moved to one fresh Modal sandbox per child. That is reliable, but concurrent fan-out now multiplies sandbox startup overhead and active sandbox usage, and we sometimes approach our provider concurrency limits.

Desired behavior

The exact API is not important, but an illustrative shape might be:

run_a = RunConfig(
    sandbox=SandboxRunConfig(
        session=shared_sandbox,
        cwd="tasks/task-a",
    )
)

run_b = RunConfig(
    sandbox=SandboxRunConfig(
        session=shared_sandbox,
        cwd="tasks/task-b",
    )
)

await asyncio.gather(
    Runner.run(agent_a, task_a, run_config=run_a),
    Runner.run(agent_b, task_b, run_config=run_b),
)

For run_a:

• shell commands without an explicit workdir start under tasks/task-a;
• a relative shell workdir is interpreted beneath tasks/task-a;
• view_image("page.png") reads tasks/task-a/page.png;
• an apply_patch operation on notes.md edits tasks/task-a/notes.md.

The scope should be bound to the run or its prepared capabilities, rather than implemented by mutating session-global cwd or path-policy state. That matters when multiple runs share the session concurrently.

Other desirable properties:

• Omitting cwd preserves current behavior.
• Manifest.root, session lifecycle, snapshots, and direct BaseSandboxSession operations remain session-scoped.
• run_as and filesystem permissions remain orthogonal and continue to compose with the path scope.
• Built-in workspace-backed capabilities have one consistent relative-path base.
• The design can support distinct scopes for concurrent runs sharing one developer-owned session.

Minimal model-free reproduction

import asyncio

from agents.sandbox import Manifest
from agents.sandbox.capabilities.tools import (
    ExecCommandArgs,
    ExecCommandTool,
    ViewImageArgs,
    ViewImageTool,
)
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

PNG = (
    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0l"
    "EQVR42mP8/x8AAwMCAO+a84QAAAAASUVORK5CYII="
)


async def main() -> None:
    client = UnixLocalSandboxClient()
    session = await client.create(manifest=Manifest())

    try:
        async with session:
            await session.mkdir("tasks/a", parents=True)

            shell = ExecCommandTool(session=session)
            view_image = ViewImageTool(session=session)

            await shell.run(
                ExecCommandArgs(
                    cmd=f"printf '%s' '{PNG}' | base64 -d > plot.png",
                    workdir="tasks/a",
                )
            )

            print(await view_image.run(ViewImageArgs(path="plot.png")))
            print(
                type(
                    await view_image.run(
                        ViewImageArgs(path="tasks/a/plot.png")
                    )
                ).__name__
            )
    finally:
        await client.delete(session)


asyncio.run(main())

image path `plot.png` was not found
ToolOutputImage

Non-goals

• This does not need to be a chroot or security boundary.
• It does not replace separate sandboxes for untrusted agents, different images, or genuine compute isolation.
• It does not require per-run mounts, users, groups, or environments.
• It does not address child-agent orchestration or result delivery.
• Deliberate access through absolute paths or .. could remain a separate policy decision; the immediate need is consistent handling of relative paths.