Overview of Sandbox Tiers
The system classifies execution into three tiers (A, B, and C). The selection of a tier is governed by theSandboxProcessRunnerPolicy crates/palyra-daemon/src/sandbox_runner.rs#81-93 and the specific requirements of the tool being executed.
| Tier | Technology | Isolation Level | Primary Use Case |
|---|---|---|---|
| Tier-A | Wasmtime (WebAssembly) | Software-defined (SFI) | High-density plugins, Skills, and portable logic. |
| Tier-B | Unix rlimit / In-process | Resource-constrained process | Legacy Unix-style resource quotas (CPU/Memory). |
| Tier-C | OS-Native (bwrap/sandbox-exec) | Kernel-level namespaces | Arbitrary binary execution with filesystem/network jails. |
Sandbox Architecture Data Flow
The following diagram illustrates how a tool call is routed through the policy engine and dispatched to the appropriate sandbox tier. Tool Execution and Sandboxing FlowTier-A: Wasm Runtime (wasmtime)
Tier-A execution useswasmtime to provide a high-performance, secure sandbox for WebAssembly modules. This is the primary execution environment for Skills and inline plugins.
Implementation Details
- Runtime: Built on
palyra-plugins-runtimewhich wrapswasmtime::Enginecrates/palyra-plugins/runtime/src/lib.rs#105-108. - Fuel Injection: Uses Wasmtime’s fuel mechanism to enforce deterministic execution limits crates/palyra-plugins/runtime/src/lib.rs#174.
- Capability Grants: Access to external resources (HTTP, Secrets, Storage) is managed via
CapabilityGrantSetcrates/palyra-plugins/runtime/src/lib.rs#42-48.
Guardrails
- Memory Limits: Configurable via
RuntimeLimits.max_memory_bytescrates/palyra-plugins/runtime/src/lib.rs#26. - Table/Instance Limits: Prevents resource exhaustion attacks by limiting table elements and instance counts crates/palyra-plugins/runtime/src/lib.rs#27-28.
Tier-B: Unix rlimit In-Process
Tier-B provides a lightweight isolation layer for Unix-like systems. It relies on standard process resource limits (rlimit) to constrain CPU time and memory usage.
Key Characteristics
- Scope: Requires a Unix-compatible platform crates/palyra-daemon/src/sandbox_runner.rs#159-165.
- Executor Name: Identified as
sandbox_tier_bin attestations crates/palyra-daemon/src/sandbox_runner.rs#124. - Constraints: Enforces
cpu_time_limit_msandmemory_limit_bytesat the OS level during process spawn.
Tier-C: OS-Native Sandboxing
Tier-C is the most restrictive tier, using platform-specific kernel features to create an isolated execution environment.Backend Implementation
Thepalyra-sandbox crate abstracts the platform-specific backends:
- Linux: Uses
bubblewrap(bwrap) to create mount namespaces, PID namespaces, and network unsharing crates/palyra-sandbox/src/lib.rs#105-184. - macOS: Uses
sandbox-execwith a generated Scheme profile. - Windows: Uses Job Objects for resource accounting and restriction.
Command Planning
Thebuild_command_plan function transforms a generic TierCCommandRequest into a platform-specific execution plan crates/palyra-sandbox/src/lib.rs#86-91.
Tier-C Command Construction (Linux Example)
Egress and Workspace Enforcement
Security is enforced not just through isolation, but through strict validation of inputs and outputs.Egress Enforcement Modes
Controlled byEgressEnforcementMode crates/palyra-daemon/src/sandbox_runner.rs#47-51:
- None: No egress restrictions.
- Preflight: Validates requested hosts against an allowlist before execution.
- Strict: Enforces network isolation at the sandbox level (e.g.,
--unshare-netinbwrap) crates/palyra-sandbox/src/lib.rs#176-178.
Workspace Scope Validation
Before execution, the runner validates that all file paths and arguments stay within the authorized workspace:- Canonicalization: Resolves the workspace root to an absolute path crates/palyra-daemon/src/sandbox_runner.rs#172.
- Scope Check:
validate_argument_workspace_scopeensures that any path arguments provided to the command do not escape the workspace boundary crates/palyra-daemon/src/sandbox_runner.rs#175-180.
Interpreter Guardrails
To prevent shell injection and escape, the system implements anINTERPRETER_EXECUTABLE_DENYLIST crates/palyra-daemon/src/sandbox_runner.rs#30-44. This prevents tools from accidentally or maliciously spawning shells like bash, powershell, or python unless explicitly allowed by the policy allow_interpreters crates/palyra-daemon/src/sandbox_runner.rs#86.
Resource and Output Budgets
To prevent “denial of service” via logs or infinite loops, the sandbox enforces strict budgets:| Budget Type | Description | Implementation |
|---|---|---|
| Execution Timeout | Total wall-clock time allowed for the process. | execution_timeout crates/palyra-daemon/src/sandbox_runner.rs#150. |
| Output Budget | Maximum bytes allowed for combined stdout/stderr. | max_output_bytes crates/palyra-daemon/src/sandbox_runner.rs#92. |
| Fuel Budget | Deterministic instruction count (Tier-A only). | fuel_budget crates/palyra-plugins/runtime/src/lib.rs#25. |
Output Enforcement
Theexecute_process function captures streams using a StreamCapture struct crates/palyra-daemon/src/sandbox_runner.rs#141-145. If the cumulative bytes exceed max_output_bytes, the process is immediately terminated with a QuotaExceeded error crates/palyra-daemon/src/sandbox_runner.rs#219-227.