Skip to content

Sandbox

autogen.beta.tools.sandbox.base.Sandbox #

Bases: Protocol

Low-level execution backend.

A Sandbox runs an argv list inside a working directory and returns combined output with an exit code. It is the shared primitive on top of which the higher-level adapters are built:

  • :class:~autogen.beta.tools.sandbox.adapter.ShellAdapter — one run(command) per shell command, applied filters, sync facade.
  • :class:~autogen.beta.tools.sandbox.adapter.CodeAdapter — one run(code, language) per code snippet, language matrix.

Implementations target local subprocesses, Docker containers, Daytona sandboxes, SSH, or anything else. Adding a new backend = one new Sandbox class. Both shell and code semantics come for free via the adapters.

Sandbox is async-only. Construction is cheap; backend resources are acquired on __aenter__ (or first call when __aenter__ is a no-op, as for :class:LocalSandbox) and released on __aexit__.

workdir property #

workdir

Working directory in which argv is executed, as seen inside the sandbox.

POSIX even on a Windows host so the same path is meaningful across backends.

host_workdir property #

host_workdir

Host-side view of :attr:workdir, when one exists.

Returns None for backends whose workdir is not visible on the host filesystem (e.g. remote Daytona sandboxes).

exec async #

exec(argv, *, env=None, timeout=None)

Execute argv and return its output.

PARAMETER DESCRIPTION
argv

Command and arguments. Always a normal argv list — no shell parsing happens on this layer. Callers that need shell features pass ["sh", "-c", cmd] explicitly (the :class:ShellAdapter does this for them).

TYPE: list[str]

env

Extra environment variables merged into the process environment. None inherits the parent environment as-is.

TYPE: dict[str, str] | None DEFAULT: None

timeout

Per-call timeout in seconds. None uses the backend's default. On timeout, the implementation must terminate the process and return exit_code=124.

TYPE: float | None DEFAULT: None

Source code in autogen/beta/tools/sandbox/base.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
async def exec(
    self,
    argv: list[str],
    *,
    env: dict[str, str] | None = None,
    timeout: float | None = None,
) -> ExecResult:
    """Execute ``argv`` and return its output.

    Args:
        argv: Command and arguments. Always a normal argv list — no
              shell parsing happens on this layer. Callers that need
              shell features pass ``["sh", "-c", cmd]`` explicitly
              (the :class:`ShellAdapter` does this for them).
        env: Extra environment variables merged into the process
             environment. ``None`` inherits the parent environment as-is.
        timeout: Per-call timeout in seconds. ``None`` uses the
                 backend's default. On timeout, the implementation
                 must terminate the process and return
                 ``exit_code=124``.
    """
    ...

put_file async #

put_file(path, content)

Write content to path inside the sandbox.

path is relative to :attr:workdir (absolute paths are rejected to keep writes confined to the workdir).

Optional capability. Backends without filesystem write support raise :class:NotImplementedError.

Source code in autogen/beta/tools/sandbox/base.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
async def put_file(self, path: PurePosixPath, content: bytes) -> None:
    """Write ``content`` to ``path`` inside the sandbox.

    ``path`` is relative to :attr:`workdir` (absolute paths are
    rejected to keep writes confined to the workdir).

    Optional capability. Backends without filesystem write support
    raise :class:`NotImplementedError`.
    """
    ...

remove_file async #

remove_file(path)

Delete path inside the sandbox. Best-effort; never raises if the file is already gone.

path is relative to :attr:workdir. Used by the :class:~autogen.beta.tools.sandbox.adapter.CodeAdapter to clean up the temp files it writes for file-mode languages.

Source code in autogen/beta/tools/sandbox/base.py 
105
106
107
108
109
110
111
112
113
async def remove_file(self, path: PurePosixPath) -> None:
    """Delete ``path`` inside the sandbox. Best-effort; never raises if
    the file is already gone.

    ``path`` is relative to :attr:`workdir`. Used by the
    :class:`~autogen.beta.tools.sandbox.adapter.CodeAdapter` to clean up
    the temp files it writes for file-mode languages.
    """
    ...

aclose async #

aclose()

Release backend resources.

Equivalent to __aexit__. Safe to call multiple times.

Source code in autogen/beta/tools/sandbox/base.py 
115
116
117
118
119
120
async def aclose(self) -> None:
    """Release backend resources.

    Equivalent to ``__aexit__``. Safe to call multiple times.
    """
    ...