Security model

A production sandbox is built from two independent layers:

1. The isolation backend running inside the sandbox pod, which constrains the sandboxed process (filesystem, syscalls, capabilities, network namespace).
2. The pod runtime, which is whether the pod’s syscalls hit the host kernel directly or go through a user-space kernel like gVisor.

These are independent. A sandbox pod can run userns inside a gVisor pod, or bubblewrap inside a vanilla container pod. Pick each layer for what it actually defends against.

Isolation backends

The library reports the backend on each process as proc.backend. On a remote sandbox, set it with SandboxEnvironment(sandbox_mode=...).

Both userns and bubblewrap layer namespaces, dropped capabilities, a Landlock filesystem ruleset, and a seccomp BPF deny-list. They are not equally strong though: bubblewrap is the stronger backend. With CAP_SYS_ADMIN it pivots into a fresh mount root, which closes the gap where the sandbox shares the pod’s root filesystem. userns is the lite variant: it runs in a vanilla pod with no extra capabilities, but it leaves that shared-rootfs gap open, so its mount isolation is weaker.

The remote default is userns because it runs anywhere (bwrap needs CAP_SYS_ADMIN + unconfined AppArmor and isn’t always present in minimal images). When you can grant the pod those capabilities and want the strongest in-pod isolation, choose bubblewrap.

Pod security for the bubblewrap backend

bubblewrap runs as a non-root user via unprivileged user namespaces. But the containerd default seccomp profile only permits the mount / pivot_root / setns / unshare syscalls bwrap needs when the container’s capability set includes CAP_SYS_ADMIN, and the default AppArmor profile must be unconfined so those calls aren’t blocked.

flyte.PodTemplate().allow_nested_sandboxing() grants exactly that: CAP_SYS_ADMIN plus unconfined AppArmor, allowPrivilegeEscalation: false. How you apply it depends on the transport:

• On-device: put it on the task that opens the session, since the sandbox child runs in that pod.

  bwrap_env = flyte.TaskEnvironment(
      name="sandboxed-task",
      image=sb.base_sandbox_image,
      pod_template=flyte.PodTemplate().allow_nested_sandboxing(),
  )
  
  @bwrap_env.task
  async def main() -> str:
      async with sb.on_device.session(backend="bubblewrap") as sbx:
          ...

• Remote: the SandboxEnvironment derives the pod template from sandbox_mode / sys_cap_admin for you and sandbox_mode="bwrap" carries the grant automatically. See Deployment.

The userns backend needs none of this because it runs in a vanilla pod. Choose userns when you can’t (or don’t want to) grant the pod extra capabilities; choose bubblewrap when you can, for its stronger isolation — at the cost of the CAP_SYS_ADMIN + AppArmor grant above.

Blast radius: why remote

The backend constrains the sandboxed process. What an escaping process can reach is determined by where the sandbox runs.

A remote sandbox runs in its own pod with:

• a typically minimal image (no caller code, no toolchain)
• its own service account (no task secrets, no cloud credentials)
• no access to whatever the caller mounted

The escape blast radius is the sandbox pod, not your workload. Hardening that pod with gVisor (below) further reduces what an escape can do to the host kernel.

Pod runtime: gVisor

Independent from the in-pod backend:

• sandbox_mode (userns or bwrap) selects the in-pod backend constraining the sandboxed process.
• runtime (container or gvisor) selects how the pod itself is run.

Setting runtime="gvisor" puts runtimeClassName: gvisor on the sandbox pod, so its syscalls go through the gVisor application kernel rather than hitting the host kernel directly. Recommended whenever the sandboxed code is untrusted or the workload is multi-tenant.

hardened = sb.SandboxEnvironment(
    name="hardened-sandbox",
    sandbox_mode="userns",
    runtime="gvisor",
)

Choosing a posture

Backend choice does affect isolation strength: bubblewrap is stronger than userns-lite (it closes the shared-rootfs gap, as above), so prefer bubblewrap when the pod can carry CAP_SYS_ADMIN + AppArmor and userns when it can’t. But both are solid process-level isolation that’s fine for production in a normal container pod. You don’t need gVisor to run a sandbox responsibly. The bigger lever as trust drops is the pod runtime (container vs gvisor) and tenant isolation (shared SandboxEnvironment vs one per tenant).

The principle: let the workload pick the floor, let the threat model pick the ceiling. The default backend is the floor and is appropriate for the common case. Reach for gVisor when you’re actually running hostile code or sharing the system across tenants — not as a blanket requirement.

What’s not in scope

• Side-channel attacks (timing, cache, Spectre-class) are not addressed by any backend here. If you need defense against them, you need hardware partitioning, not a sandbox.
• Resource exhaustion is bounded by Resources(...) on the sandbox pod and per-call timeout_s on run(). The backends do not prevent a sandboxed process from using all the CPU and memory the pod gives it.
• The proxy-based network allow-list is not a kernel-level firewall. See Networking for what it does and does not protect against.

Related

• Networking. Per-call network_mode and what the allow-list actually constrains.
• Filesystem. Default filesystem allow-list and how to extend it.
• Deployment. SandboxEnvironment, custom images, and per-launch overrides.