Sandbox Tier Architecture
The execution environment is divided into three tiers, each offering different levels of isolation and resource control.| Tier | Technology | Use Case | Primary Enforcement |
|---|---|---|---|
| Tier-A | WebAssembly (Wasmtime) | Skill Plugins | Fuel budgets, memory linear isolation, WIT-based capability grants. |
| Tier-B | OS rlimit (Unix) | Basic Tool Execution | Process-level resource limits (CPU, Memory) on standard Unix processes. |
| Tier-C | bwrap / sandbox-exec | Hardened Execution | Namespace isolation (Linux) or Seatbelt profiles (macOS) with filesystem re-rooting. |
Tier-A: WASM Plugin Runtime
WASM execution is handled by thepalyra-plugins-runtime crate, utilizing wasmtime with strict capability-based security.
- Isolation: Linear memory isolation and deterministic execution via fuel consumption crates/palyra-plugins/runtime/src/lib.rs#117-118.
- Capability Grants: Access to external resources (HTTP, Secrets, Storage) is explicitly granted via
CapabilityGrantSetcrates/palyra-plugins/runtime/src/lib.rs#43-48. - Resource Controls: Limits include
fuel_budget,max_memory_bytes, andmax_instancescrates/palyra-plugins/runtime/src/lib.rs#24-29.
Tier-B & Tier-C: Process Execution
Native process execution is managed by thesandbox_runner.rs in the daemon.
- Tier-B: Relies on standard Unix resource controls. It is restricted to Unix platforms for CPU/Memory quota enforcement crates/palyra-daemon/src/sandbox_runner.rs#159-165.
- Tier-C: Utilizes platform-specific “heavy” sandboxing. On Linux, it uses
bubblewrap(bwrap) to unshare PIDs and network namespaces crates/palyra-sandbox/src/lib.rs#131-134. On macOS, it utilizessandbox-execcrates/palyra-sandbox/src/lib.rs#10-20.
Validation Pipeline & Egress Enforcement
Before any process is spawned, it must pass through a multi-stage validation pipeline defined inrun_constrained_process crates/palyra-daemon/src/sandbox_runner.rs#147-209.
1. Input Validation
The runner parsesProcessRunnerToolInput and enforces strict constraints on the command shape:
- Command Length: Max 256 characters crates/palyra-daemon/src/sandbox_runner.rs#25.
- Argument Limits: Max 128 arguments, each limited to 4,096 bytes crates/palyra-daemon/src/sandbox_runner.rs#26-27.
- Interpreter Denylist: Blocks direct execution of shells and language runtimes (e.g.,
bash,python,node) unless explicitly allowed by policy crates/palyra-daemon/src/sandbox_runner.rs#30-44.
2. Workspace Scoping
The system ensures that the command and all its arguments are scoped within theworkspace_root.
validate_argument_workspace_scopechecks that any path-like arguments do not escape the designated workspace crates/palyra-daemon/src/sandbox_runner.rs#175-180.
3. Egress Enforcement Modes
Palyra implements three levels of network egress control crates/palyra-daemon/src/sandbox_runner.rs#46-62:- None: No network restrictions.
- Preflight: Checks requested hosts against an allowlist before execution but does not enforce at the kernel level.
- Strict: Requires kernel-level enforcement (e.g.,
unshare-netinbwrap). If the backend cannot enforce this, execution is denied crates/palyra-daemon/src/sandbox_runner.rs#192-194.
Execution & Output Capture
Process Lifecycle Flow
The following diagram illustrates the flow from aToolCall to actual process execution via the SandboxProcessRunner.
Title: Tool Execution Logic Flow
Sources: crates/palyra-daemon/src/sandbox_runner.rs#147-209, crates/palyra-daemon/src/tool_protocol.rs#13-16, crates/palyra-sandbox/src/lib.rs#86-91
Output Capture and Quotas
The daemon capturesstdout and stderr using StreamCapture crates/palyra-daemon/src/sandbox_runner.rs#141-145.
- Polling: The runner polls the process pipes every 5ms crates/palyra-daemon/src/sandbox_runner.rs#28.
- Termination: If the cumulative output exceeds
max_output_bytes, the process is forcibly terminated crates/palyra-daemon/src/sandbox_runner.rs#219-227. - Timeouts: Processes are killed if they exceed the
execution_timeoutcrates/palyra-daemon/src/sandbox_runner.rs#210-218.
Attestation & Security Metadata
Every tool execution generates aToolAttestation which is stored in the ToolExecutionOutcome crates/palyra-daemon/src/tool_protocol.rs#83-88. This provides an audit trail of how the code was executed.
ToolAttestation Fields:
execution_sha256: Hash of the input and command crates/palyra-daemon/src/tool_protocol.rs#75.executor: The specific backend used (e.g.,sandbox_tier_c_linux_bubblewrap) crates/palyra-daemon/src/tool_protocol.rs#78.sandbox_enforcement: TheEgressEnforcementModeapplied crates/palyra-daemon/src/tool_protocol.rs#79.
Code Entity Mapping
The following diagram maps high-level security concepts to specific Rust structs and functions. Title: Sandbox Entity Mapping Sources: crates/palyra-daemon/src/sandbox_runner.rs#81-93, crates/palyra-sandbox/src/lib.rs#53-57, crates/palyra-daemon/src/tool_protocol.rs#73-80, crates/palyra-daemon/src/wasm_plugin_runner.rs#18-30Tier-C Implementation Details
Thepalyra-sandbox crate abstracts the platform-specific complexities of Tier-C execution.
Linux (Bubblewrap)
TheLinuxBubblewrapBackend builds a command plan that:
- Clears the environment (
--clearenv) crates/palyra-sandbox/src/lib.rs#165. - Mounts a minimal
/proc,/dev, and/tmpcrates/palyra-sandbox/src/lib.rs#133-141. - Bind-mounts essential system libraries (e.g.,
/usr,/lib) as read-only crates/palyra-sandbox/src/lib.rs#145-147. - Bind-mounts the
workspace_rootas the only writable area crates/palyra-sandbox/src/lib.rs#159-162. - Optionally unshares the network stack (
--unshare-net) for isolation crates/palyra-sandbox/src/lib.rs#176-178.
macOS (sandbox-exec)
Uses the native Seatbelt framework. It generates temporary profiles that restrict filesystem access to the workspace and block network sockets based on theTierCPolicy crates/palyra-sandbox/src/lib.rs#10-20.
Sources: crates/palyra-sandbox/src/lib.rs#81-184