CodexSandboxExecutionPolicy Class — langchain Architecture

Architecture documentation for the CodexSandboxExecutionPolicy class in _execution.py from the langchain codebase.

Class python

Entity Profile

Dependency Diagram

graph TD
  270607fa_c99a_3911_2c2a_8e2c42ed30ef["CodexSandboxExecutionPolicy"]
  54947cfa_44ad_df6e_ebe6_8908dfdafc92["BaseExecutionPolicy"]
  270607fa_c99a_3911_2c2a_8e2c42ed30ef -->|extends| 54947cfa_44ad_df6e_ebe6_8908dfdafc92
  a7063f14_dbac_d9f7_9cc6_a20aa09f5461["_execution.py"]
  270607fa_c99a_3911_2c2a_8e2c42ed30ef -->|defined in| a7063f14_dbac_d9f7_9cc6_a20aa09f5461
  338d8d25_6ab3_9c8d_1642_bc64d57428eb["spawn()"]
  270607fa_c99a_3911_2c2a_8e2c42ed30ef -->|method| 338d8d25_6ab3_9c8d_1642_bc64d57428eb
  e4dfd7ef_1e04_5414_759b_eeaddac35815["_build_command()"]
  270607fa_c99a_3911_2c2a_8e2c42ed30ef -->|method| e4dfd7ef_1e04_5414_759b_eeaddac35815
  3e8d5e89_0a16_467a_a1cf_2c14a1472ea3["_resolve_binary()"]
  270607fa_c99a_3911_2c2a_8e2c42ed30ef -->|method| 3e8d5e89_0a16_467a_a1cf_2c14a1472ea3
  86c76604_9ef0_684c_c50e_47b8e1363077["_determine_platform()"]
  270607fa_c99a_3911_2c2a_8e2c42ed30ef -->|method| 86c76604_9ef0_684c_c50e_47b8e1363077
  94ee1582_75a2_cf18_d5c4_76e3e62ebf08["_format_override()"]
  270607fa_c99a_3911_2c2a_8e2c42ed30ef -->|method| 94ee1582_75a2_cf18_d5c4_76e3e62ebf08

Relationship Graph

Source Code

libs/langchain_v1/langchain/agents/middleware/_execution.py lines 191–263

class CodexSandboxExecutionPolicy(BaseExecutionPolicy):
    """Launch the shell through the Codex CLI sandbox.

    Ideal when you have the Codex CLI installed and want the additional syscall and
    filesystem restrictions provided by Anthropic's Seatbelt (macOS) or Landlock/seccomp
    (Linux) profiles. Commands still run on the host, but within the sandbox requested by
    the CLI. If the Codex binary is unavailable or the runtime lacks the required
    kernel features (e.g., Landlock inside some containers), process startup fails with a
    `RuntimeError`.

    Configure sandbox behavior via `config_overrides` to align with your Codex CLI
    profile. This policy does not add its own resource limits; combine it with
    host-level guards (cgroups, container resource limits) as needed.
    """

    binary: str = "codex"
    platform: typing.Literal["auto", "macos", "linux"] = "auto"
    config_overrides: Mapping[str, typing.Any] = field(default_factory=dict)

    def spawn(
        self,
        *,
        workspace: Path,
        env: Mapping[str, str],
        command: Sequence[str],
    ) -> subprocess.Popen[str]:
        full_command = self._build_command(command)
        return _launch_subprocess(
            full_command,
            env=env,
            cwd=workspace,
            preexec_fn=None,
            start_new_session=False,
        )

    def _build_command(self, command: Sequence[str]) -> list[str]:
        binary = self._resolve_binary()
        platform_arg = self._determine_platform()
        full_command: list[str] = [binary, "sandbox", platform_arg]
        for key, value in sorted(dict(self.config_overrides).items()):
            full_command.extend(["-c", f"{key}={self._format_override(value)}"])
        full_command.append("--")
        full_command.extend(command)
        return full_command

    def _resolve_binary(self) -> str:
        path = shutil.which(self.binary)
        if path is None:
            msg = (
                "Codex sandbox policy requires the '%s' CLI to be installed and available on PATH."
            )
            raise RuntimeError(msg % self.binary)
        return path

    def _determine_platform(self) -> str:
        if self.platform != "auto":
            return self.platform
        if sys.platform.startswith("linux"):
            return "linux"
        if sys.platform == "darwin":  # type: ignore[unreachable, unused-ignore]
            return "macos"
        msg = (  # type: ignore[unreachable, unused-ignore]
            "Codex sandbox policy could not determine a supported platform; "
            "set 'platform' explicitly."
        )
        raise RuntimeError(msg)

    @staticmethod
    def _format_override(value: typing.Any) -> str:
        try:
            return json.dumps(value)
        except TypeError:
            return str(value)