Struct ProcessSandboxConfig 

pub struct ProcessSandboxConfig { /* private fields */ }

Data-oriented sandbox configuration that produces a wrapper program + args prefix rather than wrapping a std::process::Command directly.

Useful when the consumer needs a different Command type (e.g. tokio::process::Command) but still wants OS-level sandbox wrapping. See Self::sandbox_prefix for the produced prefix and SandboxPolicy for what happens when the OS sandbox is unavailable.

Implementations

impl ProcessSandboxConfig

pub fn new(writable_root: impl Into<PathBuf>) -> Self

Create a new sandbox config with the given writable root.

The default sandbox policy is read from the ASTRID_SANDBOX_POLICY environment variable (required / off). When unset or unparseable, the policy defaults to SandboxPolicy::Required: callers will get an error from Self::sandbox_prefix rather than a silent unsandboxed launch when the OS-level sandbox can’t be applied.

pub fn with_policy(self, policy: SandboxPolicy) -> Self

Override the policy for handling unavailable OS-level sandboxing. See SandboxPolicy for the semantics of each variant.

pub fn with_network(self, allow: bool) -> Self

Set whether network access is allowed.

pub fn with_extra_read(self, path: impl Into<PathBuf>) -> Self

Add an additional read-only path.

pub fn with_extra_write(self, path: impl Into<PathBuf>) -> Self

Add an additional writable path.

pub fn with_hidden(self, path: impl Into<PathBuf>) -> Self

Add a path to hide from the sandboxed process.

On Linux, this overlays an empty tmpfs. On macOS, the path is excluded from the Seatbelt read allowlist.

pub fn sandbox_prefix(&self) -> Result<Option<SandboxPrefix>>

Build the sandbox wrapper prefix for this configuration.

Behaviour depends on the active SandboxPolicy:

• SandboxPolicy::Required (default): returns Ok(Some(prefix)) when the OS-level sandbox is available, or Err with an actionable hint when it is not. Callers should propagate the error and refuse to launch the subprocess — this is what preserves the README’s “subprocess capsules are always contained” guarantee.
• SandboxPolicy::Off: returns Ok(None) unconditionally, without any warning. Use only for trusted dev environments.

Errors

Returns an error if:

• Any configured path is not valid UTF-8, not absolute, or contains characters that would break sandbox profile syntax (double-quote, backslash, or null byte).
• The active policy is SandboxPolicy::Required and the OS-level sandbox is unavailable. The error message names the most likely cause (kernel.apparmor_restrict_unprivileged_userns=1 on Ubuntu 24.04+) and the remediation (sysctl command or explicit policy override).

Trait Implementations

impl Clone for ProcessSandboxConfig

fn clone(&self) -> ProcessSandboxConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ProcessSandboxConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.