Browse the documentation

Early preview

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

DimensionLinuxWindowsmacOS
1. Process tree containmentunshare(CLONE_NEWUSER, CLONE_NEWPID), prctl(PR_SET_CHILD_SUBREAPER) and cgroups v2 PID trackingWin32 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 controlA 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 directoriesA Seatbelt (sandbox_init) profile restricting file-read* and file-write* to the declared paths
3. System call filteringA seccomp-BPF allowlist or denylist compiled in pure RustWin32 process mitigation policies (DynamicCode, SystemCallDisable, ExtensionPointDisable)Seatbelt kernel trap filters denying raw debugging and kernel-extension calls
4. Network isolationCLONE_NEWNET with a user-space TCP and UDP forwarder or an eBPF socket filter enforcing the allowed inbound and outbound ports and CIDRsWindows Filtering Platform (WFP) inbound and outbound port and IP rules per AppContainerSeatbelt network-inbound and network-outbound socket rules
5. Resource quotascgroups v2 (cpu.max, memory.max, pids.max, io.max) and setrlimit (RLIMIT_NOFILE, RLIMIT_AS)Job Object extended limits and CPU rate controlsetrlimit (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_paths persist normally on disk after the application stops.
  • Reading a sensitive host path outside the policy, such as /etc/shadow, ~/.ssh or ~/.aws, is rejected immediately by the kernel with EACCES (Linux, macOS) or ERROR_ACCESS_DENIED (Windows).

System calls: three profiles

Set sandbox.syscall_profile to one of three built-in presets:

ProfileUsed forWhat it does
strictThe default for Go and Rust static binariesBlocks ptrace, kexec_load, mount, umount2, bpf, perf_event_open, unshare, chroot, init_module and raw AF_PACKET sockets.
runtime-managedSelected 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.
customYour own allowlist or denylistThe 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:

ValueBehavior
"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

KeyValuesMeaning
sandbox.enabledtrue, falseTurns 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_pathsList of pathsPaths the guest may read.
sandbox.filesystem.read_write_pathsList of pathsPaths the guest may read and write; their files persist after a stop.
sandbox.network.inbound_allow_portsList of portsPorts the guest may accept connections on.
sandbox.network.outbound_allowtrue, falseWhether the guest may open outbound connections.
sandbox.network.outbound_allow_cidrsList of CIDRsWhere outbound connections may go.