Sandbox

Sandbox Overview

Ralph TUI can run agent commands inside a sandbox to reduce access to your machine. When enabled, the sandbox limits filesystem access to your project directory and any explicit allowlists, and can disable network access.

Sandboxing is opt-in and controlled through configuration or CLI flags. Auto mode will select the most secure sandbox available for your platform.

What Sandboxing Protects

• Limits write access to your project directory and any allowPaths you list.
• Mounts system directories as read-only to reduce accidental changes.
• Can disable network access to block outbound calls.

What It Does Not Protect

• It is not a VM-level security boundary; treat it as defense in depth.
• Any paths you add to allowPaths remain writable by the agent.
• Any paths you add to readOnlyPaths remain readable by the agent.
• It does not enforce CPU, memory, or process limits.

Platform Requirements

Sandbox mode uses different backends depending on platform:

If the required backend is missing or unavailable, auto mode falls back to off.

Install Bubblewrap (Linux)

Install Bubblewrap with your package manager. On Debian/Ubuntu:

sudo apt install bubblewrap

On Fedora:

sudo dnf install bubblewrap

On Arch Linux:

sudo pacman -S bubblewrap

macOS sandbox-exec

On macOS, Ralph TUI uses the native sandbox-exec command with dynamically generated Seatbelt profiles. This provides similar isolation to Bubblewrap on Linux.

How It Works

• Ralph generates a Seatbelt profile based on your configuration
• The profile denies access by default, then allowlists specific paths
• System directories (/usr, /bin, /Applications, etc.) are read-only
• Your project directory is read-write
• Agent auth paths (e.g., ~/.claude) are mounted read-write to allow OAuth token refresh

Deprecation Notice

Apple has deprecated sandbox-exec, but it continues to work and is still used by many tools including Homebrew. You may see a deprecation warning in stderr - this is expected and does not affect functionality.

Sandboxing on Windows

Native Windows sandboxing is not currently supported. Windows users who want sandboxing should use WSL2 (Windows Subsystem for Linux).

WSL2 Setup for Sandboxing

1. Install WSL2 (if not already installed):

   POWERSHELLCopy

   wsl --install

2. Install ralph-tui inside WSL:

   BashCopy

   # Inside your WSL distribution
   curl -fsSL https://get.ralph-tui.dev | bash

3. Install Bubblewrap:

   BashCopy

   sudo apt install bubblewrap

4. Run with sandbox enabled:

   BashCopy

   ralph-tui run --sandbox

WSL2 provides a full Linux environment where Bubblewrap works natively.

Sandbox Modes

Sandbox mode is selected by the sandbox.mode setting or the CLI flag:

Configuration Options

Configure sandboxing in your config file:

[sandbox]
enabled = true
mode = "auto"
network = true
allowPaths = ["/path/to/allow"]
readOnlyPaths = ["/path/to/read-only"]

CLI Flags

CLI flags override config file settings:

Network Access Warning

The --no-network flag disables all network access inside the sandbox, including LLM API calls. This means:

• Cloud-based agents will fail: All current built-in agents (e.g. claude, opencode, droid) require network access to communicate with their respective LLM APIs. Using --no-network with these agents will cause API calls to fail.

• Ralph TUI will warn you: When you use --no-network with an agent that declares requiresNetwork: true, Ralph TUI emits a warning at startup:

  Copy

  ⚠️  Warning: Agent 'claude' requires network access but --no-network is enabled. LLM API calls will fail.
  

When --no-network Makes Sense

The --no-network flag is designed for future agent plugins that don't need network access:

If you're using the built-in cloud-based agents (for example claude, opencode, droid etc.), leave network = true (the default) or omit --no-network.

Examples

Enable sandboxing (auto mode)

ralph-tui run --sandbox

Enable sandboxing without network access

ralph-tui run --sandbox --no-network

Force Bubblewrap on Linux

[sandbox]
enabled = true
mode = "bwrap"

Force sandbox-exec on macOS

[sandbox]
enabled = true
mode = "sandbox-exec"

Add custom paths

[sandbox]
enabled = true
allowPaths = ["~/shared-workspace"]
readOnlyPaths = ["~/.config/my-tool"]