Sandbox

Run commands and agent-written programs inside an operating-system boundary.

Read the walkthrough before consulting individual signatures.

Public interfaces

Interface	Purpose
Sandbox	Run a command inside a boundary described by a SandboxPolicy.
SandboxResult	What one sandboxed run produced.
SandboxedCommand	A command rewritten to run inside a sandbox, ready for a process API.
BubblewrapSandbox	Confine commands with bubblewrap namespaces and read-only mounts (Linux).
build_bubblewrap_arguments	Render a resolved policy and a command as a bwrap argument vector.
SandboxClosedError	The session was closed (or never opened), so it cannot run anything.
SandboxCommandError	A command run with check=True did not succeed.
SandboxError	Base error for sandbox failures.
SandboxPolicyError	A policy is malformed or names something the sandbox cannot enforce.
SandboxUnavailableError	The requested sandbox cannot run on this machine.
SandboxBackend	Which sandbox implementation to use.
SandboxWarning	A sandbox was requested and this platform has none, so commands run unisolated.
create_sandbox	Create the sandbox for this machine, failing loudly rather than weakening it.
default_backend	Return the backend this platform uses when asked for AUTO.
PassthroughSandbox	Run commands with no isolation, behind the same interface as a real sandbox.
NetworkMode	How much of the network a sandboxed process can reach.
ResolvedPolicy	A policy turned into concrete absolute paths that a backend can enforce.
ResourceLimits	What a sandboxed process may use, and how much.
SandboxPolicy	The boundary a sandboxed process runs inside.
build_environment	Build the environment a sandboxed process starts with.
command_arguments	Return the argument vector for a command given as a shell string or as arguments.
resolve_policy	Turn a policy into the concrete paths a backend enforces.
CgroupHandle	One cgroup created for one run: it is created by the parent, joined by the child.
CgroupUsage	What a cgroup reports after a run.
CgroupV2	The cgroup v2 hierarchy, and whether it can host a sandbox's own group.
MemoryStrategy	Which mechanism to use for memory_bytes.
ResourcePlan	What will be done about resources for one run.
ResourceReport	How each requested limit is enforced, and what a run measured.
RlimitStep	One setrlimit call: soft and hard are both set so a process cannot raise them back.
apply_rlimits	Apply the steps. Runs in the child before exec, so it never raises.
cgroup2_mount	Return the cgroup v2 mount point, or None when the machine has no unified hierarchy.
own_cgroup_path	Return the cgroup this process belongs to, below mount.
plan_resources	Decide how to enforce limits on this machine.
plan_rlimits	Turn the POSIX limits into setrlimit calls, and say what cannot be applied.
process_tree_rss_bytes	Return the resident memory of pid, its descendants and its process group.
rlimit_support	Public constant or type alias; see its definition.
user_task_count	Return how many processes (and, on Linux, threads) this user owns right now.
watchdog_available	Whether the parent can sample a process group here.
SandboxSession	Run commands inside a sandbox with the workspace and budget you configure.
parse_size	Turn "512MB", "1.5G" or a byte count into bytes.
SeatbeltSandbox	Confine commands with a Seatbelt profile (macOS).
build_seatbelt_profile	Render a resolved policy as a Seatbelt profile and its parameters.