Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.boxlite.ai/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how to debug sandbox policy issues when developing or troubleshooting BoxLite’s macOS sandbox isolation.

​
Overview

BoxLite uses macOS’s built-in sandbox system (Seatbelt) to isolate the boxlite-shim process. The sandbox uses SBPL (Sandbox Profile Language) policies that whitelist specific operations. When an operation is denied, macOS logs the denial to the system log.

​
Quick Reference

# Real-time monitoring (recommended during development)
log stream --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAINS "boxlite"'

# Check recent denials (last 5 minutes)
log show --last 5m --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAINS "deny"'

​
Debugging Workflow

1

Enable real-time log monitoring

Open a separate terminal and start monitoring sandbox messages:
# Watch all sandbox denials
log stream --predicate 'subsystem == "com.apple.sandbox"' --level error

# Or filter for boxlite specifically
log stream --predicate 'eventMessage CONTAINS "boxlite-shim" AND eventMessage CONTAINS "deny"'
2

Run your test

In another terminal, run the operation that is failing:
source .venv/bin/activate
python -c "
import asyncio
import boxlite

async def test():
    async with boxlite.SimpleBox(image='alpine:latest') as box:
        result = await box.exec('echo', 'hello')
        print(result.stdout)

asyncio.run(test())
"
3

Analyze denials

Sandbox denials appear in the format:
kernel: (Sandbox) Sandbox: boxlite-shim(PID) deny(1) OPERATION TARGET
Common denial types:
OperationTargetMeaning
file-read-data/path/to/fileProcess tried to read file contents
file-read-metadata/pathProcess tried to stat/access file metadata
file-write-data/path/to/fileProcess tried to write to file
file-write-create/path/to/fileProcess tried to create new file
sysctl-readkern.bootargsProcess tried to read sysctl value
mach-lookupcom.apple.serviceProcess tried to connect to mach service
network-outbound*:443Process tried to make network connection
iokit-openIOHIDFamilyProcess tried to access IOKit device
4

Update the policy

Based on the denial, add the appropriate 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"))
5

Rebuild and test

After updating .sbpl files, rebuild to pick up changes:
# The .sbpl files are embedded via include_str!
# Touch the Rust file to force recompilation
make dev:python

# Or for just the Rust library
cargo clean -p boxlite && cargo build -p boxlite

​
Log Commands Reference

​
Real-time Streaming

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

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

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

# Combined: boxlite denials only
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 (replace with your target timestamps)
log show --start "2025-01-01 10:00:00" --end "2025-01-01 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"'

# Only kernel messages (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 entire directory tree
(allow file-read* (subpath "/path/to/dir"))

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

; Allow reading files matching pattern
(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"))

​
Testing Syntax

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

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

​
BoxLite Policy Files

BoxLite’s sandbox policy is split into multiple files:
FilePurpose
seatbelt_base_policy.sbplProcess ops, sysctls, mach services, IOKit
seatbelt_file_read_policy.sbplStatic system paths for reading
seatbelt_file_write_policy.sbplStatic paths for writing (/tmp)
seatbelt_network_policy.sbplNetwork access (optional)
macos.rsDynamic paths (binary, volumes, box_dir)

​
Viewing the Generated Policy

To see the complete generated policy: 
use boxlite::jailer::{SecurityOptions, write_sandbox_profile};

let security = SecurityOptions::default();
let box_dir = Path::new("/tmp/test-box");
let binary_path = Path::new("/path/to/boxlite-shim");

write_sandbox_profile(
    Path::new("/tmp/debug-policy.sbpl"),
    &security,
    box_dir,
    binary_path,
).unwrap();
Then inspect /tmp/debug-policy.sbpl.

​
Common Issues

​
1. Changes Not Taking Effect

The .sbpl files are embedded at compile time via include_str!. After modifying them: 
# Force recompilation
cargo clean -p boxlite
cargo build -p boxlite

# For Python SDK
make dev:python

​
2. Path Canonicalization

macOS uses symlinks (/var -> /private/var, /tmp -> /private/tmp). Use canonical paths in your policy: 
; Wrong - /tmp is a symlink
(allow file-write* (subpath "/tmp"))
Use the canonical path instead:
; Correct - use canonical path
(allow file-write* (subpath "/private/tmp"))

​
3. Duplicate Denials

The log may show “X duplicate reports for…”. This means the same denial happened multiple times. Fix the root cause, not each duplicate.

​
4. Silent Failures

Some denials do not appear in logs immediately. If the process hangs or crashes without logged denials:
1

Check for crash reports

ls ~/Library/Logs/DiagnosticReports/*shim*
2

Verify process started

Check host logs to ensure the process actually started.
3

Run without sandbox

Try running without the sandbox to isolate whether the issue is sandbox-related.

​
5. Permissions vs Sandbox

Not all failures are sandbox-related. Also check:
  • File permissions (ls -la)
  • Directory existence
  • Hypervisor.framework entitlements

​
Debugging Checklist

Use this checklist when investigating sandbox denials:
  • Start log streaming before running test
  • Filter logs for your process name
  • Check for deny(1) messages
  • Note the exact operation and target
  • Add minimal rule to policy (prefer literal over subpath)
  • Document WHY the rule is needed (in comments)
  • Rebuild and retest
  • Verify no new denials appear

​
Further Reading