Sandboxing
Sandboxing is a declarative switch: sandbox.enabled: true or false. When it is enabled, the Executor builds a multi-layered operating-system isolation boundary around the guest runtime, without root privileges and without a hypervisor. When it is disabled, the application runs directly on the host with standard user permissions, still under the Executor's process-tree supervision, caps and exit events.
Five dimensions of isolation
| Dimension | Linux | Windows | macOS |
|---|---|---|---|
| 1. Process tree containment | unshare(CLONE_NEWUSER, CLONE_NEWPID), prctl(PR_SET_CHILD_SUBREAPER) and cgroups v2 PID tracking | Win32 Job Objects (JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE, breakaway disabled) | A dedicated process group (setpgid) and kqueue (EVFILT_PROC with NOTE_FORK and NOTE_EXEC) |
| 2. Filesystem access control | A CLONE_NEWNS mount namespace, read-only runtime bind mounts and Landlock LSM path allowlists (ABI v1 to v5) | An AppContainer SID with explicit NTFS DACL grants on the allowed read and write directories | A Seatbelt (sandbox_init) profile restricting file-read* and file-write* to the declared paths |
| 3. System call filtering | A seccomp-BPF allowlist or denylist compiled in pure Rust | Win32 process mitigation policies (DynamicCode, SystemCallDisable, ExtensionPointDisable) | Seatbelt kernel trap filters denying raw debugging and kernel-extension calls |
| 4. Network isolation | CLONE_NEWNET with a user-space TCP and UDP forwarder or an eBPF socket filter enforcing the allowed inbound and outbound ports and CIDRs | Windows Filtering Platform (WFP) inbound and outbound port and IP rules per AppContainer | Seatbelt network-inbound and network-outbound socket rules |
| 5. Resource quotas | cgroups v2 (cpu.max, memory.max, pids.max, io.max) and setrlimit (RLIMIT_NOFILE, RLIMIT_AS) | Job Object extended limits and CPU rate control | setrlimit (RLIMIT_AS, RLIMIT_CPU, RLIMIT_NOFILE, RLIMIT_NPROC) |
CPU and memory quotas are configured in the top-level resources block and are enforced even with sandbox.enabled: false; see CPU and memory capping.
Filesystem: read-only and read-write paths
You declare exactly which host paths or relative workspace folders the guest may read and which it may change:
sandbox:
enabled: true
filesystem:
read_only_paths:
- "/etc/ssl/certs"
- "./configs"
read_write_paths:
- "./reports"
- "./logs"
- "/tmp/app-scratch"
- Files written to
read_write_pathspersist normally on disk after the application stops. - Reading a sensitive host path outside the policy, such as
/etc/shadow,~/.sshor~/.aws, is rejected immediately by the kernel withEACCES(Linux, macOS) orERROR_ACCESS_DENIED(Windows).
System calls: three profiles
Set sandbox.syscall_profile to one of three built-in presets:
| Profile | Used for | What it does |
|---|---|---|
strict | The default for Go and Rust static binaries | Blocks ptrace, kexec_load, mount, umount2, bpf, perf_event_open, unshare, chroot, init_module and raw AF_PACKET sockets. |
runtime-managed | Selected automatically for Python, JVM and V8 (Node.js) | Keeps the JIT memory protection transitions the JVM and V8 need (mprotect with PROT_EXEC), while blocking privilege escalation, kernel keyrings and host debugging calls. |
custom | Your own allowlist or denylist | The filter you define. |
A guest that triggers a fatal syscall trap is stopped with exit code 70.
Network: inbound ports, outbound CIDRs
sandbox:
network:
inbound_allow_ports: [8000]
outbound_allow: true
outbound_allow_cidrs:
- "10.0.0.0/8"
- "172.16.0.0/12"
With outbound_allow: false, the guest cannot send data to the internet.
The control plane keeps working
oee-stub forks the sandboxed child into its own network context (CLONE_NEWNET on Linux, an AppContainer SID on Windows) after it has initialized its own HTTP client. An air-gapped or port-restricted guest can therefore still be governed by an external HTTPS exit event: the supervisor keeps polling while the guest cannot reach the network. The inbound webhook listener also runs in the supervisor's network context and is never reachable through the guest sandbox.
Inside containers: container fallback
Default Docker and Kubernetes seccomp profiles often block nested CLONE_NEWUSER or mount calls with EPERM. At startup, the Executor probes what the kernel allows (CapEff in /proc/self/status and the Landlock ABI version) and follows sandbox.container_fallback:
| Value | Behavior |
|---|---|
"auto" (default) | Layers every unprivileged primitive the container permits: Landlock filesystem rules, seccomp-BPF filtering, PR_SET_CHILD_SUBREAPER containment and setrlimit quotas. No --privileged and no --cap-add=SYS_ADMIN on docker run. |
"strict" | Refuses to launch the guest if any requested namespace primitive is unavailable, with exit code 69. |
Containers and Kubernetes covers running the Executor as a container's PID 1.
Sandbox keys
| Key | Values | Meaning |
|---|---|---|
sandbox.enabled | true, false | Turns the isolation boundary on or off. |
sandbox.container_fallback | "auto", "strict" | What to do when a namespace primitive is unavailable. |
sandbox.syscall_profile | "strict", "runtime-managed", "custom" | The system-call filter. |
sandbox.filesystem.read_only_paths | List of paths | Paths the guest may read. |
sandbox.filesystem.read_write_paths | List of paths | Paths the guest may read and write; their files persist after a stop. |
sandbox.network.inbound_allow_ports | List of ports | Ports the guest may accept connections on. |
sandbox.network.outbound_allow | true, false | Whether the guest may open outbound connections. |
sandbox.network.outbound_allow_cidrs | List of CIDRs | Where outbound connections may go. |