Debug macOS Seatbelt denials - BoxLite Documentation

Finding which rule fired needs nothing but an installed SDK. Changing the policy needs a source checkout and a rebuild — on a published SDK, capture the deny line and file it upstream instead of editing the policy locally.

Prerequisites

A working BoxLite install (Python boxlite or Node @boxlite-ai/boxlite) and a machine with hardware virtualization — see Installation.
Command-line tools: log (Unified Logging, ships with the system), sandbox-exec (at /usr/bin/sandbox-exec, ships with the system).
To modify and rebuild the policy: you need the BoxLite source tree and the Rust toolchain (cargo), plus the make environment for the Python SDK.

Note: Seatbelt is a macOS-specific isolation mechanism. On Linux, BoxLite uses bwrap/landlock (src/boxlite/src/jailer/sandbox/bwrap.rs, landlock.rs), and the SBPL debugging flow on this page does not apply.

Quick Example (minimal flow)

The core of debugging is two steps: start monitoring first, then run the triggering operation. First terminal — real-time monitoring of boxlite-related Sandbox denials:

# Real-time streaming monitor (recommended during development): show only boxlite denials
log stream --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAINS "boxlite" AND eventMessage CONTAINS "deny"'

Second terminal — run a minimal operation that exercises the isolation layer (copy and run directly):

# pip install boxlite  (latest published version)
import asyncio
import boxlite

async def main() -> None:
    try:
        # SimpleBox is an async context manager; create + start happen only on entering async with
        async with boxlite.SimpleBox(image="alpine:latest") as box:
            # A non-zero exit code does not raise; check exit_code yourself
            result = await box.exec("echo", "hello")
            if result.exit_code != 0:
                print(f"non-zero exit: {result.exit_code}\n{result.stderr}")
            else:
                print(result.stdout)
    except RuntimeError as exc:
        # No virtualization / image pull failure / Sandbox start failure may all raise a standard RuntimeError
        print(f"box failed to start: {exc}")

if __name__ == "__main__":
    asyncio.run(main())

Back in the first terminal: if a deny(1) line appears, one of the box’s operations was blocked by Seatbelt — see the “Debugging Workflow” below.

Debugging Workflow

Step 1: Start real-time log monitoring first

Start monitoring in a separate terminal (always start monitoring before running the test, otherwise you miss early denials):

# View all sandbox denials (error level only)
log stream --predicate 'subsystem == "com.apple.sandbox"' --level error

# Or filter only denials from the boxlite-shim process
log stream --predicate 'eventMessage CONTAINS "boxlite-shim" AND eventMessage CONTAINS "deny"'

Step 2: Run the triggering operation

In another terminal, run the operation that fails (reuse the Quick Example above, or substitute your actual use-case script):

# If using the project's bundled venv
source .venv/bin/activate
python your_repro_script.py

Step 3: Interpret the denial

The format of a Sandbox denial in the log:

kernel: (Sandbox) Sandbox: boxlite-shim(PID) deny(1) OPERATION TARGET

Common denial types:

Operation	Target example	Meaning
`file-read-data`	`/path/to/file`	The process tried to read file contents
`file-read-metadata`	`/path`	The process tried to stat / access file metadata
`file-write-data`	`/path/to/file`	The process tried to write to a file
`file-write-create`	`/path/to/file`	The process tried to create a new file
`sysctl-read`	`kern.bootargs`	The process tried to read a sysctl value
`mach-lookup`	`com.apple.service`	The process tried to connect to a mach service
`network-outbound`	`*:443`	The process tried to make a network connection
`iokit-open`	`IOHIDFamily`	The process tried to access an IOKit device

Step 4: Update the policy

Based on the denial, add the corresponding allow rule to the SBPL policy:

; For file-read-data /var
(allow file-read* (literal "/var"))

; For sysctl-read kern.bootargs
(allow sysctl-read (sysctl-name "kern.bootargs"))

; For mach-lookup com.apple.service
(allow mach-lookup (global-name "com.apple.service"))

Step 5: Rebuild and retest

The .sbpl files are embedded at compile time via include_str!, so changes take effect only after a rebuild:

# Rebuild only the Rust library
cargo clean -p boxlite && cargo build -p boxlite

# Rebuild the Python SDK (along with the native extension)
make dev:python

Log command reference

Real-time streaming

# All sandbox messages
log stream --predicate 'subsystem == "com.apple.sandbox"'

# Errors only (denials)
log stream --predicate 'subsystem == "com.apple.sandbox"' --level error

# Specific process
log stream --predicate 'eventMessage CONTAINS "boxlite-shim"'

# Combined: show only boxlite denials
log stream --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAINS "boxlite" AND eventMessage CONTAINS "deny"'

Historical queries

# Last N minutes
log show --last 5m --predicate 'eventMessage CONTAINS "Sandbox:"'

# Time range
log show --start "2024-01-06 10:00:00" --end "2024-01-06 10:05:00" --predicate 'subsystem == "com.apple.sandbox"'

# Count denials by type
log show --last 10m --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAINS "deny"' | grep -oE 'deny\(1\) [^ ]+' | sort | uniq -c | sort -rn

Filtering tips

# Exclude noisy system processes
log show --last 5m --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAINS "deny" AND NOT eventMessage CONTAINS "imagent" AND NOT eventMessage CONTAINS "bluetoothd"'

# Kernel messages only (most reliable)
log show --last 5m --predicate 'senderImagePath == "/kernel" AND eventMessage CONTAINS "Sandbox:"'

SBPL policy syntax

Basic structure

(version 1)

; Deny everything by default
(deny default)

; Allow specific operations
(allow process-exec)
(allow file-read* (subpath "/usr/lib"))
(allow sysctl-read (sysctl-name "hw.ncpu"))

Common patterns

; Allow reading an entire directory tree
(allow file-read* (subpath "/path/to/dir"))

; Allow reading a single file only
(allow file-read* (literal "/path/to/file"))

; Allow reading files matching a regex
(allow file-read* (regex #"^/Users/[^/]+/\.boxlite/"))

; Allow multiple sysctls
(allow sysctl-read
    (sysctl-name "hw.ncpu")
    (sysctl-name "hw.memsize")
    (sysctl-name-prefix "kern.proc."))

; Allow mach service lookup
(allow mach-lookup
    (global-name "com.apple.CoreServices.coreservicesd")
    (global-name "com.apple.system.logger"))

Validating syntax

# Test whether the policy syntax is valid (inline policy)
sandbox-exec -p '(version 1)(deny default)(allow process-exec)' /bin/echo "Policy OK"

# Test with a policy file
sandbox-exec -f /path/to/policy.sbpl /bin/echo "Policy OK"
# Replace /path/to/policy.sbpl with the path to your policy file

BoxLite policy files

BoxLite’s Seatbelt policy is split across several files: the static fragments are in src/boxlite/resources/seatbelt/, and the dynamic assembly is in src/boxlite/src/jailer/sandbox/seatbelt.rs:

File	Purpose
`src/boxlite/resources/seatbelt/seatbelt_base_policy.sbpl`	Process ops, sysctls, mach services, IOKit; contains `(deny default)`
`src/boxlite/resources/seatbelt/seatbelt_file_read_policy.sbpl`	Static system paths allowed for reading
`src/boxlite/resources/seatbelt/seatbelt_file_write_policy.sbpl`	Static paths allowed for writing (e.g. `/tmp`)
`src/boxlite/resources/seatbelt/seatbelt_network_policy.sbpl`	Network access (optional)
`src/boxlite/src/jailer/sandbox/seatbelt.rs`	Dynamic policy assembly (binary path, mounted volumes, box directory)

Viewing the full generated policy

The full runtime policy is assembled by build_sandbox_policy() in src/boxlite/src/jailer/sandbox/seatbelt.rs and passed directly via sandbox-exec -p. The absolute path of sandbox-exec is hardcoded to /usr/bin/sandbox-exec (the constant SANDBOX_EXEC_PATH, to prevent PATH injection). When debugging, focus on:

The static fragments: src/boxlite/resources/seatbelt/*.sbpl
Dynamic path grants: build_dynamic_read_paths() and build_dynamic_write_paths() (both in seatbelt.rs)
The denial records from log show / log stream, used to locate the missing allow clause

Troubleshooting

Changes to `.sbpl` did not take effect

The .sbpl files are embedded into the binary at compile time via include_str! (see the consts at the top of seatbelt.rs). After modifying them, you must force a rebuild:

# Force a recompile of the Rust library
cargo clean -p boxlite
cargo build -p boxlite

# Python SDK
make dev:python

Path canonicalization (symlink problem)

macOS uses symlinks: /var -> /private/var, /tmp -> /private/tmp. The policy must use the canonicalized real path:

; Wrong -- /tmp is a symlink; the rule will not match
(allow file-write* (subpath "/tmp"))

; Correct -- use the canonical path
(allow file-write* (subpath "/private/tmp"))

Duplicate denials

The log may show “X duplicate reports for…”, meaning the same denial happened multiple times. Fix the root cause; you do not need to handle each one individually.

Silent failure (no log, but a hang/crash)

Some denials are not written to the log immediately. If the process hangs or crashes without a denial record:

Check the crash reports: ls ~/Library/Logs/DiagnosticReports/*shim*
Confirm the process actually started: check the host logs
Temporarily run with sandbox isolation off to narrow it down (see the next item)

Distinguishing “permissions” from “sandbox”

Not all failures are caused by Sandbox. Also check:

File permissions (ls -la)
Whether the directory exists
Hypervisor.framework entitlements

Narrow the problem with a security preset (SDK layer)

To tell whether the problem is caused by the isolation layer, temporarily switch the security level in the SDK. Note: security options are passed via advanced=AdvancedBoxOptions(security=...); there is no top-level security= keyword, and AdvancedBoxOptions lives only under the boxlite.boxlite submodule (not exported at the top level):

import asyncio
import boxlite
from boxlite import SecurityOptions
from boxlite.boxlite import AdvancedBoxOptions  # not exported at the top level; import from the submodule

async def main() -> None:
    # Presets: development() / standard() / maximum() (there is no .minimum())
    # Security options are passed via advanced=AdvancedBoxOptions(security=...); there is no top-level security= keyword.
    # SimpleBox forwards extra kwargs (including advanced) to the underlying BoxOptions.
    try:
        async with boxlite.SimpleBox(
            image="alpine:latest",
            advanced=AdvancedBoxOptions(security=SecurityOptions.development()),
        ) as box:
            # SimpleBox.exec returns an ExecResult (output already drained); the timeout parameter is timeout (float)
            result = await box.exec("echo", "hello", timeout=10.0)
            if result.exit_code != 0:
                print(f"non-zero exit: {result.exit_code}\n{result.stderr}")
            else:
                print(result.stdout)
    except RuntimeError as exc:
        print(f"failed: {exc}")

if __name__ == "__main__":
    asyncio.run(main())

If you want to manage the lifecycle manually with the native Boxlite + Box handles: the native Box.exec(...) returns an Execution (not an ExecResult); you must await execution.wait() to get the exit code and read the stdout()/stderr() streams; remove with runtime.remove(box.id, force=True) (on the runtime, not box.remove()). The SimpleBox form above already drains output automatically, which is more convenient for debugging.

If a box fails to start with SecurityOptions.maximum() but works with development(), the Seatbelt policy is almost certainly missing an allow rule — go back to Step 1 and capture the deny line.

Start fails outright / no virtualization

macOS starts the microVM via Apple Hypervisor.framework (no /dev/kvm required). If the machine has no hardware virtualization or the entitlement is missing, the box fails to start and raises a standard RuntimeError (the process stays alive and can be caught with try/except).

Image pull failure raises `RuntimeError` (not `BoxliteError`)

A missing command or an image pull failure raises a standard RuntimeError (Python) / bare Error (Node), not BoxliteError. See Error Handling.

Debugging checklist

Start log stream before running the test
Filter logs by process name (boxlite-shim)
Look for deny(1) messages
Record the exact operation and target
Add a minimal rule (prefer literal over subpath)
Document in a comment why the rule is needed
Rebuild and retest
Confirm no new denials appear

​Prerequisites

​Quick Example (minimal flow)

​Debugging Workflow

​Step 1: Start real-time log monitoring first

​Step 2: Run the triggering operation

​Step 3: Interpret the denial

​Step 4: Update the policy

​Step 5: Rebuild and retest

​Log command reference

​Real-time streaming

​Historical queries

​Filtering tips

​SBPL policy syntax

​Basic structure

​Common patterns

​Validating syntax

​BoxLite policy files

​Viewing the full generated policy

​Troubleshooting

​Changes to .sbpl did not take effect

​Path canonicalization (symlink problem)

​Duplicate denials

​Silent failure (no log, but a hang/crash)

​Distinguishing “permissions” from “sandbox”

​Narrow the problem with a security preset (SDK layer)

​Start fails outright / no virtualization

​Image pull failure raises RuntimeError (not BoxliteError)

​Debugging checklist

​Further reading