> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox Process Runner

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * crates/palyra-cli/src/args/system.rs
  * crates/palyra-cli/src/commands/sandbox.rs
  * crates/palyra-cli/src/commands/system.rs
  * crates/palyra-cli/tests/help\_snapshots/message-help.txt
  * crates/palyra-cli/tests/help\_snapshots/system-help.txt
  * crates/palyra-common/src/process\_runner\_input.rs
  * crates/palyra-daemon/src/application/approvals/mod.rs
  * crates/palyra-daemon/src/application/instruction\_compiler.rs
  * crates/palyra-daemon/src/application/memory.rs
  * crates/palyra-daemon/src/application/recall.rs
  * crates/palyra-daemon/src/application/route\_message/tool\_flow\.rs
  * crates/palyra-daemon/src/application/service\_authorization.rs
  * crates/palyra-daemon/src/application/tool\_registry/builtin.rs
  * crates/palyra-daemon/src/application/tool\_registry/tests.rs
  * crates/palyra-daemon/src/application/tool\_runtime/memory.rs
  * crates/palyra-daemon/src/application/tool\_security.rs
  * crates/palyra-daemon/src/execution\_backends.rs
  * crates/palyra-daemon/src/gateway/tests.rs
  * crates/palyra-daemon/src/maintenance.rs
  * crates/palyra-daemon/src/sandbox\_runner.rs
  * crates/palyra-daemon/src/self\_healing.rs
  * crates/palyra-daemon/src/transport/grpc/services/memory/service.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/maintenance.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/system.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/webhooks.rs
  * schemas/proto/palyra/v1/memory.proto
</details>

The Sandbox Process Runner is the execution engine for the `palyra.process.run` tool. It provides a multi-tiered isolation strategy for executing arbitrary shell commands and binaries, ranging from direct host execution with resource constraints to fully isolated containerized environments. It enforces strict security guardrails including executable allowlisting, path scoping, and egress network control.

## Execution Tiers

Palyra implements a tiered isolation model to balance performance and security requirements. The runner selects the appropriate tier based on the `SandboxProcessRunnerPolicy` configured for the session [crates/palyra-daemon/src/sandbox\_runner.rs#5-13](http://crates/palyra-daemon/src/sandbox_runner.rs#5-13).

| Tier       | Isolation Mechanism    | Description                                                                                                                                                                                                                                                                   |
| :--------- | :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tier B** | Direct Spawn + rlimits | Spawns the child process directly on the host with a scrubbed environment, workspace-scoped path arguments, and Unix `rlimit` quotas [crates/palyra-daemon/src/sandbox\_runner.rs#6-7](http://crates/palyra-daemon/src/sandbox_runner.rs#6-7).                                |
| **Tier C** | Sandbox Backends       | Delegates isolation to specialized backends like `Docker`, `bubblewrap`, or `sandbox_exec`. It fails closed if the requested network isolation cannot be enforced [crates/palyra-daemon/src/sandbox\_runner.rs#8-10](http://crates/palyra-daemon/src/sandbox_runner.rs#8-10). |

### Tier B Implementation

Tier B relies on host-level OS primitives. On Unix-like systems, it applies `rlimit` quotas to bound CPU and memory usage [crates/palyra-daemon/src/sandbox\_runner.rs#6-7](http://crates/palyra-daemon/src/sandbox_runner.rs#6-7). On Windows, it utilizes **Job Objects** to ensure process trees are managed together and terminated cleanly [crates/palyra-daemon/src/sandbox\_runner.rs#41-50](http://crates/palyra-daemon/src/sandbox_runner.rs#41-50).

### Tier C Implementation

Tier C uses `palyra-sandbox` to build a `TierCCommandPlan` [crates/palyra-daemon/src/sandbox\_runner.rs#66-69](http://crates/palyra-daemon/src/sandbox_runner.rs#66-69). This plan abstracts the specific container or sandbox technology, ensuring that egress policies and filesystem mounts are applied consistently across different backends.

Sources: [crates/palyra-daemon/src/sandbox\_runner.rs#1-15](http://crates/palyra-daemon/src/sandbox_runner.rs#1-15), [crates/palyra-daemon/src/sandbox\_runner.rs#66-70](http://crates/palyra-daemon/src/sandbox_runner.rs#66-70).

## Security Guardrails

The runner operates on a **deny-by-default** principle. Every validation failure results in a security rejection [crates/palyra-daemon/src/sandbox\_runner.rs#14-15](http://crates/palyra-daemon/src/sandbox_runner.rs#14-15).

### 1. Input Validation and Caps

To prevent resource exhaustion or injection attacks at the invocation level, the runner enforces hard limits on the input shape:

* **Max Command Length:** 256 characters [crates/palyra-daemon/src/sandbox\_runner.rs#75](http://crates/palyra-daemon/src/sandbox_runner.rs#75).
* **Max Argument Count:** 128 [crates/palyra-daemon/src/sandbox\_runner.rs#76](http://crates/palyra-daemon/src/sandbox_runner.rs#76).
* **Max Environment Variables:** 32 [crates/palyra-daemon/src/sandbox\_runner.rs#78](http://crates/palyra-daemon/src/sandbox_runner.rs#78).

### 2. Executable Allowlisting

The runner checks the requested command against `allowed_executables`. Additionally, common interpreters (e.g., `bash`, `python`, `node`) are explicitly denylisted unless the `allow_interpreters` policy is enabled [crates/palyra-daemon/src/sandbox\_runner.rs#138-152](http://crates/palyra-daemon/src/sandbox_runner.rs#138-152).

### 3. Environment Scrubbing

To prevent the leakage of daemon secrets (like provider API keys or vault paths), the child process environment is rebuilt from a small allowlist of safe keys, such as `HOME`, `USER`, and `LANG` [crates/palyra-daemon/src/sandbox\_runner.rs#119-122](http://crates/palyra-daemon/src/sandbox_runner.rs#119-122).

### 4. Egress Enforcement

Outbound network access is policed via `EgressEnforcementMode` [crates/palyra-daemon/src/sandbox\_runner.rs#156-157](http://crates/palyra-daemon/src/sandbox_runner.rs#156-157):

* **Strict:** Only explicitly allowed hosts are reachable.
* **Block All:** No network access permitted.
* **Allow All:** (Not recommended for untrusted code).

Sources: [crates/palyra-daemon/src/sandbox\_runner.rs#73-82](http://crates/palyra-daemon/src/sandbox_runner.rs#73-82), [crates/palyra-daemon/src/sandbox\_runner.rs#119-122](http://crates/palyra-daemon/src/sandbox_runner.rs#119-122), [crates/palyra-daemon/src/sandbox\_runner.rs#138-152](http://crates/palyra-daemon/src/sandbox_runner.rs#138-152).

## Process Lifecycle and Management

The runner supports both foreground (synchronous) and background (asynchronous) execution modes.

### Background Processes

Background processes are governed by a `BackgroundLifetimeMode` [crates/palyra-common/src/process\_runner\_input.rs#12-24](http://crates/palyra-common/src/process_runner_input.rs#12-24):

* **RunOwned:** Process is terminated when the agent run ends.
* **Detached:** Process continues until its bounded lifetime (max 30 minutes) expires [crates/palyra-daemon/src/sandbox\_runner.rs#113](http://crates/palyra-daemon/src/sandbox_runner.rs#113).

### Output Capture and Redaction

The runner captures `stdout` and `stderr` in chunks (default 4KB) [crates/palyra-daemon/src/sandbox\_runner.rs#86](http://crates/palyra-daemon/src/sandbox_runner.rs#86). Before output is returned to the model, it passes through a redaction pipeline that scrubs sensitive URL segments (e.g., `token`, `password`) [crates/palyra-daemon/src/sandbox\_runner.rs#130-133](http://crates/palyra-daemon/src/sandbox_runner.rs#130-133).

### Execution Flow Diagram

```mermaid theme={null}
graph TD
    subgraph "Natural Language Space"
        UserMsg["'Run npm install'"]
    end

    subgraph "Code Entity Space"
        PRTI["ProcessRunnerToolInput"]
        PRV["SandboxProcessRunner (run_tool)"]
        Policy["SandboxProcessRunnerPolicy"]
        TierB["Tier B (Direct Spawn)"]
        TierC["Tier C (Sandbox Backend)"]
        Redact["redact_url_segments_in_text"]
    end

    UserMsg --> PRTI
    PRTI --> PRV
    PRV --> Policy
    Policy -- "Check Permissions" --> PRV
    PRV -- "Direct Host" --> TierB
    PRV -- "Containerized" --> TierC
    TierB --> Redact
    TierC --> Redact
    Redact --> Result["ToolExecutionOutcome"]
```

Sources: [crates/palyra-daemon/src/sandbox\_runner.rs#1-3](http://crates/palyra-daemon/src/sandbox_runner.rs#1-3), [crates/palyra-common/src/process\_runner\_input.rs#47-67](http://crates/palyra-common/src/process_runner_input.rs#47-67), [crates/palyra-daemon/src/sandbox\_runner.rs#130-133](http://crates/palyra-daemon/src/sandbox_runner.rs#130-133).

## Windows Job Objects

On Windows, Palyra uses `CreateJobObjectW` and `AssignProcessToJobObject` to manage the lifecycle of spawned processes [crates/palyra-daemon/src/sandbox\_runner.rs#42-50](http://crates/palyra-daemon/src/sandbox_runner.rs#42-50).

Key features include:

* **Kill on Close:** Ensuring that if the daemon or the runner handle closes, the entire process tree is terminated [crates/palyra-daemon/src/sandbox\_runner.rs#48](http://crates/palyra-daemon/src/sandbox_runner.rs#48).
* **Resource Accounting:** Using `JobObjectBasicAccountingInformation` to track CPU and memory usage across the process group [crates/palyra-daemon/src/sandbox\_runner.rs#47](http://crates/palyra-daemon/src/sandbox_runner.rs#47).

Sources: [crates/palyra-daemon/src/sandbox\_runner.rs#38-50](http://crates/palyra-daemon/src/sandbox_runner.rs#38-50).

## Tool Registration and Schema

The `palyra.process.run` tool is registered as a builtin tool with a specific JSON schema that defines the model's interface.

```mermaid theme={null}
classDiagram
    class ToolRegistryEntry {
        +String name: "palyra.process.run"
        +ToolParallelismPolicy parallelism
        +ToolResultProjectionPolicy projection
    }
    class ProcessRunnerToolInput {
        +String command
        +Vec~String~ args
        +Option~String~ cwd
        +Map~String, String~ env
        +bool background
    }
    ToolRegistryEntry ..> ProcessRunnerToolInput : defines schema for
```

Sources: [crates/palyra-daemon/src/application/tool\_registry/builtin.rs#23-25](http://crates/palyra-daemon/src/application/tool_registry/builtin.rs#23-25), [crates/palyra-common/src/process\_runner\_input.rs#47-67](http://crates/palyra-common/src/process_runner_input.rs#47-67).