Struct SandboxConfig 

pub struct SandboxConfig {
    pub enabled: bool,
    pub profile: SandboxProfile,
    pub allow_read: Vec<PathBuf>,
    pub allow_write: Vec<PathBuf>,
    pub strict: bool,
    pub backend: String,
    pub denied_domains: Vec<String>,
    pub fail_if_unavailable: bool,
}

OS-level subprocess sandbox configuration ([tools.sandbox] TOML section).

When enabled = true, all shell commands are wrapped in an OS-native sandbox:

• macOS: sandbox-exec (Seatbelt) with a generated TinyScheme profile.
• Linux (requires sandbox cargo feature): bwrap + Landlock + seccomp BPF.

This sandbox applies only to subprocess executors (shell). In-process executors (WebScrapeExecutor, FileExecutor) are not covered — see NFR-SB-1.

Examples

[tools.sandbox]
enabled = true
profile = "workspace"
allow_read  = ["$HOME/.cache/zeph"]
allow_write = ["./.local"]
strict = true
backend = "auto"

Fields

enabled: bool

Enable OS-level sandbox. Default: false.

On Linux requires the sandbox cargo feature. When true but the feature is absent, startup emits WARN and degrades to noop (fail-open). Use strict = true to make the feature absence an error instead.

profile: SandboxProfile

Enforcement profile controlling the baseline restrictions.

allow_read: Vec<PathBuf>

Additional paths granted read access. Resolved to absolute paths at startup.

allow_write: Vec<PathBuf>

Additional paths granted write access. Resolved to absolute paths at startup.

strict: bool

When true, sandbox initialization failure aborts startup (fail-closed). Default: true.

backend: String

OS backend hint: "auto" / "seatbelt" / "landlock-bwrap" / "noop".

"auto" selects the best available backend for the current platform.

denied_domains: Vec<String>

Hostnames (or single-level wildcard patterns) denied network egress from sandboxed subprocesses. Enforcement is platform-specific:

• macOS Seatbelt: injects (deny network* (remote host "<host>")) rules after (allow network*) so Seatbelt’s last-rule-wins semantics block the listed hosts.
• Linux bwrap: mounts a synthetic /etc/hosts that resolves denied names to 0.0.0.0. This is best-effort — processes using custom DNS clients, IP literals, or HTTP proxies can bypass this filter.

On NoopSandbox (unsupported platform), denied domains cannot be enforced. See fail_if_unavailable to make that a startup error instead of a warning.

Patterns follow the same syntax as [tools.scrape].denied_domains: exact hostname or *.suffix (single subdomain level).

fail_if_unavailable: bool

When true, failure to activate an effective OS sandbox (noop selected, backend missing, or platform unsupported) aborts startup with an error.

This is stricter than strict: strict only gates missing backend binary errors, while fail_if_unavailable additionally rejects NoopSandbox selection (e.g. on an unsupported platform). Default: false.

Implementations

impl SandboxConfig

pub fn validate_denied_domains(&self) -> Result<(), String>

Validate denied_domains entries.

Each entry must contain only alphanumeric characters, dots, hyphens, and an optional leading * wildcard. Returns Err with a descriptive message on the first invalid entry.

Errors

Returns an error string when any pattern contains invalid characters.

Trait Implementations

impl Clone for SandboxConfig

fn clone(&self) -> SandboxConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SandboxConfig

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

Formats the value using the given formatter.

impl Default for SandboxConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SandboxConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for SandboxConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.