Sandbox & Execution Isolation

YeePilot runs every command inside an isolated sandbox that restricts what the command can access and how many resources it can consume. Even if a command behaves unexpectedly, the sandbox prevents it from causing widespread damage to your system.

How the Sandbox Works

When YeePilot executes a command, it creates an isolated execution environment using Linux namespaces. This is the same technology that powers container runtimes like Docker, applied at the individual command level.

Each command runs with:

• Process isolation -- the command cannot see or interact with processes outside its namespace
• Resource limits -- CPU, memory, file size, and process count are all capped
• Path restrictions -- sensitive system files are inaccessible
• Output truncation -- runaway output is cut off before it floods your terminal
• Execution timeout -- commands that run too long are terminated automatically

Resource Limits

YeePilot enforces default resource limits on every command:

These defaults are designed to handle legitimate administrative tasks while preventing runaway processes from consuming server resources.

Customizing Resource Limits

Adjust limits in ~/.yeepilot/config.yaml under the sandbox section:

sandbox:
  enabled: true
  cpu_limit: 300          # CPU seconds
  memory_limit: 512       # Megabytes
  file_size_limit: 100    # Megabytes
  process_limit: 64       # Max processes
  output_limit: 10000     # Characters
  timeout: 30             # Seconds (wall-clock)

For resource-intensive tasks like compiling software or processing large log files, you may need to increase these limits:

sandbox:
  memory_limit: 1024      # 1 GB for compilation tasks
  timeout: 120            # 2 minutes for long-running builds
  output_limit: 50000     # More output for verbose logs

Denied Paths

Certain sensitive paths are blocked by default, preventing commands from reading or modifying critical system files:

Commands that attempt to access denied paths will fail with a permission error.

Customizing Denied Paths

Add or modify denied paths in your configuration:

sandbox:
  denied_paths:
    - /etc/shadow
    - /etc/gshadow
    - /root
    - /var/lib/secrets       # Custom: your application secrets
    - /opt/myapp/keys        # Custom: application key store

This is particularly useful for protecting application-specific secret stores or configuration directories that should never be accessed through YeePilot.

Network Access

By default, commands executed through YeePilot have network access so that tasks like package installation (apt install), updates, and health checks work normally.

You can restrict network access for tighter isolation:

sandbox:
  network: true            # true (default) or false

Setting network: false blocks all outbound and inbound network connections from executed commands. This is useful in high-security environments where you want to ensure commands only operate on local resources.

PTY Support

YeePilot uses pseudo-terminal (PTY) allocation for command execution. This means commands behave as if they are running in a real terminal, which ensures:

• Correct output formatting -- tools that detect terminal capabilities (like colored output, progress bars) work properly
• Interactive compatibility -- commands that require terminal features function correctly
• Signal handling -- Ctrl+C and other signals are delivered properly to running commands

Output Truncation

When a command produces more output than the configured limit (default: 10,000 characters), YeePilot truncates it and notifies you:

> Search all log files for errors
 
Running: grep -r "ERROR" /var/log/
 
[Output truncated at 10,000 characters -- 45,230 total characters produced]
... showing last portion of output ...

This prevents a single command from overwhelming your session. If you need to see the full output, you can:

1. Increase the output_limit in your configuration
2. Redirect output to a file: "Search for errors and save results to /tmp/errors.log"
3. Use more specific queries to reduce output volume

Execution Timeout

Commands are terminated after 30 seconds of wall-clock time by default. This protects against:

• Accidentally running commands that hang indefinitely
• Commands stuck waiting for network resources
• Infinite loops or runaway processes

When a command times out, YeePilot terminates it cleanly and reports the timeout:

Command timed out after 30 seconds: ping 10.0.0.1

Increase the timeout for commands that legitimately need more time:

sandbox:
  timeout: 120             # 2 minutes

Full Sandbox Configuration Reference

Here is a complete sandbox configuration with all available options:

sandbox:
  enabled: true            # Enable/disable sandbox (default: true)
  cpu_limit: 300           # CPU seconds (default: 300)
  memory_limit: 512        # Megabytes (default: 512)
  file_size_limit: 100     # Megabytes (default: 100)
  process_limit: 64        # Max processes (default: 64)
  output_limit: 10000      # Characters (default: 10000)
  timeout: 30              # Wall-clock seconds (default: 30)
  network: true            # Allow network access (default: true)
  denied_paths:            # Paths commands cannot access
    - /etc/shadow
    - /etc/gshadow
    - /root

Note: Disabling the sandbox entirely (enabled: false) removes all isolation and resource limits. This is strongly discouraged for production use. Only disable the sandbox in controlled development environments where you fully trust the commands being executed.