Skip to content

Sandbox Mode

Sandbox mode runs PatchPal inside an isolated Docker or Podman container, providing security boundaries for AI agent operations. This is the recommended way to run PatchPal, especially for autopilot mode or when working with untrusted code.

Quick Start

# Interactive mode
patchpal-sandbox --env-file .env -- --model anthropic/claude-sonnet-4-5

# Autopilot mode
patchpal-sandbox --env-file .env -- autopilot --prompt-file task.md

# With local Ollama (requires --host-network)
patchpal-sandbox --host-network -- --model ollama_chat/glm-4.7-flash:q4_K_M

The -- separator distinguishes sandbox options (left side) from PatchPal arguments (right side).

Why Use Sandbox Mode?

Security Benefits

1. Ephemeral Filesystem - Container is destroyed after each session (--rm flag) - Malicious code can't persist backdoors - File modifications isolated to mounted /workspace

2. Network Isolation (with --restrict-network) - Blocks data exfiltration attempts - Prevents backdoor downloads - Allows only whitelisted endpoints

3. Resource Limits - Memory and CPU constraints prevent resource exhaustion - Protects host system from runaway processes

4. Process Isolation - Agent runs in separate namespace - Can't access host processes or system files (outside mounts)

Convenience Benefits

  • ✅ Pre-built image with patchpal installed (fast startup)
  • ✅ Auto-detects Docker/Podman (prefers Podman rootless)
  • ✅ Loads API keys from .env files
  • ✅ Mounts custom tools automatically
  • ✅ Clean environment on each run

Installation

No separate installation needed - patchpal-sandbox is included with PatchPal:

pip install patchpal
patchpal-sandbox --help

First Run: Downloads pre-built container image (~150MB, one-time) Subsequent Runs: Start instantly (no pip install needed)

Updating the image: Run docker pull ghcr.io/amaiya/patchpal-sandbox:latest (or podman pull) to get the latest version.

Windows Setup (Podman)

On Windows, if using Podman, you need to set up a Podman machine before using patchpal-sandbox:

Step 1: Create and start Podman machine

podman machine init --rootful
podman machine start

Note: Use --rootful mode to avoid socket permission issues. This is the recommended configuration for Windows.

Step 2: Configure corporate firewall certificates (if behind a corporate firewall)

If you're behind a corporate firewall with SSL inspection, you need to add your company's CA certificates to the Podman machine so it can pull Docker images:

podman machine ssh

Inside the Podman machine:

# Create directory for CA certificates
sudo mkdir -p /etc/pki/ca-trust/source/anchors/

# Copy your company's CA bundle
# (You should already have this if Python/pip works with your firewall)
sudo vi /etc/pki/ca-trust/source/anchors/your-company-ca-bundle.crt
# Paste the certificate content and save

# Update the CA trust store
sudo update-ca-trust

# Exit the SSH session
exit

Finding your CA bundle: - If Python/pip already works, check: %SSL_CERT_FILE% or %REQUESTS_CA_BUNDLE% - Contact your IT department for the corporate root CA certificate - Common locations: C:\Program Files\CompanyCerts\ or similar

After completing these steps, patchpal-sandbox should work correctly.

Troubleshooting: - If podman machine start fails, try: podman machine stop && podman machine start - If certificate errors persist, verify the certificate was copied correctly: podman machine ssh -- cat /etc/pki/ca-trust/source/anchors/your-company-ca-bundle.crt - To recreate the machine: podman machine stop && podman machine rm && podman machine init --rootful && podman machine start

Basic Usage

Interactive Mode

# Using .env file for API keys
patchpal-sandbox --env-file .env -- --model anthropic/claude-sonnet-4-5

# Passing API key directly
patchpal-sandbox -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY -- --model anthropic/claude-sonnet-4-5

# Using multiple .env files (later files override earlier)
patchpal-sandbox --env-file .env --env-file .env.local -- --model openai/gpt-4o

In interactive mode, permissions are enabled and you'll be prompted before destructive operations.

Autopilot Mode

# From prompt file
patchpal-sandbox --env-file .env -- autopilot \
  --model anthropic/claude-sonnet-4-5 \
  --prompt-file task.md \
  --max-iterations 30

# Inline prompt
patchpal-sandbox --env-file .env -- autopilot \
  --model openai/gpt-4o \
  --prompt "Build a calculator with tests"

In autopilot mode, permissions are automatically disabled for safety. See Autopilot Mode for comprehensive documentation.

Local Models (Ollama)

When using local Ollama models, use --host-network to access the host's Ollama service:

patchpal-sandbox --host-network -- --model ollama_chat/glm-4.7-flash:q4_K_M

# Autopilot with Ollama
patchpal-sandbox --host-network -- autopilot \
  --model ollama_chat/qwen2.5-coder:32b \
  --prompt-file task.md

Note: --host-network shares the host's network stack with the container (required for localhost:11434 access). This bypasses network isolation - only use with trusted local models.

Network Restrictions

For maximum security, use --restrict-network to isolate the container from the external network while allowing access to required LLM APIs:

# Auto-detects LLM endpoints from environment variables
patchpal-sandbox \
  --restrict-network \
  --env-file .env \
  -- autopilot --prompt-file task.md

# With custom allowed URLs
patchpal-sandbox \
  --restrict-network \
  --allow-url https://api.openai.com \
  --allow-url https://custom-api.example.com \
  --env-file .env \
  -- autopilot --prompt-file task.md

What Gets Blocked

With --restrict-network, the firewall blocks: - ❌ GitHub, PyPI, npm, Docker Hub - ❌ General internet access (google.com, etc.) - ❌ Data exfiltration attempts - ❌ Backdoor downloads

Auto-Detected LLM Endpoints

The sandbox automatically detects and allows these endpoints based on your environment variables:

Provider Environment Variable Endpoint Allowed
OpenAI OPENAI_API_KEY https://api.openai.com
Anthropic ANTHROPIC_API_KEY https://api.anthropic.com
Google AI GEMINI_API_KEY https://generativelanguage.googleapis.com
AWS Bedrock AWS_REGION Region-specific endpoint
Azure OpenAI AZURE_OPENAI_RESOURCE https://<resource>.openai.azure.com
Groq GROQ_API_KEY https://api.groq.com
Cohere COHERE_API_KEY https://api.cohere.ai
Together TOGETHER_API_KEY https://api.together.xyz
Replicate REPLICATE_API_KEY https://api.replicate.com

Custom endpoints are also detected from variables like: - OPENAI_BASE_URL, OPENAI_API_BASE, OPENAI_ENDPOINT - ANTHROPIC_BASE_URL, ANTHROPIC_API_BASE - AWS_BEDROCK_ENDPOINT, AWS_ENDPOINT_URL_BEDROCK_RUNTIME - Any *_BASE_URL, *_API_BASE, *_ENDPOINT pattern

Testing Network Restrictions

Validate firewall rules without running PatchPal:

patchpal-sandbox \
  --restrict-network \
  --test-restrictions \
  --env-file .env

This tests that: - Blocked sites (google.com, github.com) are inaccessible - Allowed LLM endpoints are accessible - Returns exit code 0 on success, 1 on failure

AWS Bedrock GovCloud Example

# .env.govcloud file:
# AWS_ACCESS_KEY_ID=...
# AWS_SECRET_ACCESS_KEY=...
# AWS_BEDROCK_REGION=us-gov-east-1

patchpal-sandbox \
  --restrict-network \
  --env-file .env.govcloud \
  -- autopilot \
  --model bedrock/arn:aws-us-gov:bedrock:us-gov-east-1::inference-profile/us-gov.anthropic.claude-sonnet-4-5-20250929-v1:0 \
  --prompt-file task.md

The sandbox automatically detects us-gov-east-1 and allows https://bedrock-runtime.us-gov-east-1.amazonaws.com.

Security Considerations

⚠️ Container credentials: AWS credentials passed via --env-file are visible to the container. However: - Exfiltration is still blocked by network restrictions - Credentials don't persist after container exit - Only affects that specific session - .env file is not readable/accessible by agent.

For maximum security: - Use short-lived credentials (IAM roles, temporary tokens) - Use restrictive IAM policies (minimum required permissions) - Monitor AWS CloudTrail for unexpected API calls

Advanced Options

Container Runtime Selection

# Force Docker (default: auto-detect)
patchpal-sandbox --runtime docker -- --model anthropic/claude-sonnet-4-5

# Force Podman
patchpal-sandbox --runtime podman -- --model groq/llama-3.3-70b-versatile

Auto-detection logic: 1. Check if podman is available → use Podman rootless 2. Fallback to docker

Custom Container Image

# Use latest PyPI version (slower startup - requires pip install)
patchpal-sandbox --image python:3.11-slim -- --model anthropic/claude-sonnet-4-5

# Use specific patchpal version
patchpal-sandbox --image ghcr.io/amaiya/patchpal-sandbox:0.21.8 -- --model openai/gpt-4o

Default image: ghcr.io/amaiya/patchpal-sandbox:latest (pre-built, fast startup)

Additional Volume Mounts

# Mount additional directories
patchpal-sandbox \
  -v /path/to/data:/data:ro \
  -v /path/to/output:/output \
  -- --model anthropic/claude-sonnet-4-5

Environment Variables

Environment variable behavior depends on whether --env-file is provided:

Without --env-file (uses host environment): 

# Host environment variables (AWS_*, OPENAI_*, etc.) are passed through
patchpal-sandbox -- --model openai/gpt-4o

With --env-file (isolated mode): 

# ONLY variables from .env file are used (better isolation)
# Host environment variables are NOT passed
patchpal-sandbox --env-file .env -- --model anthropic/claude-sonnet-4-5

Note: When using --env-file, host environment variables are intentionally excluded for better security isolation. This prevents accidental credential leakage from your shell environment.

Resource Limits

# Memory and CPU limits
patchpal-sandbox \
  --memory 4g \
  --cpus 2 \
  -- autopilot --prompt-file task.md

Custom Tools

Custom tools work automatically in sandbox mode:

  • Global tools: ~/.patchpal/tools/ (auto-mounted)
  • Repository tools: <repo>/.patchpal/tools/ (in /workspace)

See Custom Tools for details on creating tools.

Troubleshooting

"docker: command not found"

Install Docker or Podman:

# Ubuntu/Debian
sudo apt-get install podman

# macOS
brew install podman
podman machine init
podman machine start

# RHEL/Fedora
sudo dnf install podman

"Permission denied" errors

Podman rootless (recommended): No sudo required, works out of the box.

Docker: Add your user to the docker group: 

sudo usermod -aG docker $USER
# Log out and back in

Firewall rules not working

If --restrict-network isn't blocking traffic:

  1. Test restrictions explicitly: 

    patchpal-sandbox --restrict-network --test-restrictions --env-file .env

  2. Verify iptables inside container: 

    patchpal-sandbox --restrict-network --shell
$ iptables -L -n

  3. Check that Podman has necessary capabilities (automatically added by patchpal-sandbox)

Slow startup times

The default pre-built image should start in under 1 second after the initial download.

To pre-download or update the image: 

docker pull ghcr.io/amaiya/patchpal-sandbox:latest
# or
podman pull ghcr.io/amaiya/patchpal-sandbox:latest

Note: The sandbox image is updated periodically with PatchPal releases.

Corporate proxy/firewall issues

If you're behind a corporate proxy:

# Pass proxy settings
patchpal-sandbox \
  -e HTTP_PROXY=$HTTP_PROXY \
  -e HTTPS_PROXY=$HTTPS_PROXY \
  -e NO_PROXY=$NO_PROXY \
  -- --model anthropic/claude-sonnet-4-5

SSL certificates are auto-mounted from: - /etc/ssl/certs/ca-certificates.crt - /etc/pki/tls/certs/ca-bundle.crt - /etc/ssl/ca-bundle.pem

For Windows Podman with corporate firewalls, see the Windows Setup section above.

Comparison with Manual Docker/Podman

patchpal-sandbox --env-file .env -- autopilot --prompt-file task.md

✅ Automatic container setup ✅ Pre-built image (fast startup) ✅ Auto-detects runtime (Podman/Docker) ✅ Auto-configures Ollama context ✅ Auto-mounts custom tools ✅ Auto-mounts SSL certs ✅ Network restriction support

Manual Docker Command

docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.patchpal:/root/.patchpal \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  --memory="2g" --cpus="2" \
  ghcr.io/amaiya/patchpal-sandbox:latest \
  bash -c "patchpal-autopilot --prompt-file task.md"

❌ More verbose ❌ Manual volume mounts ❌ Manual environment setup ❌ No auto-detection ❌ No network restrictions

Recommendation: Use patchpal-sandbox for simplicity and consistency.

Best Practices

Always Use Sandbox For

  • ✅ Autopilot mode (REQUIRED for safety)
  • ✅ Untrusted code/repositories
  • ✅ Automated workflows
  • ✅ Production environments
  • ✅ Repositories with sensitive data

Consider Sandbox For

  • ✅ General development (extra safety layer)
  • ✅ Testing/experimentation
  • ✅ Learning PatchPal

Optional Without Sandbox

  • Direct use on trusted throwaway projects
  • One-off interactive sessions on isolated VMs
  • Cases where you need direct host access

Network Restriction Recommendations

Scenario Use --restrict-network?
Autopilot mode ✅ YES (strongly recommended)
Untrusted code ✅ YES
Production automation ✅ YES
Personal projects ⚠️ Optional (adds defense-in-depth)
Trusted code + human oversight ⚠️ Optional
Local models only (Ollama) ❌ NO (requires --host-network)

Examples

Multi-Phase Development Workflow

# Phase 1: Core functionality with Claude
patchpal-sandbox --env-file .env -- autopilot \
  --model anthropic/claude-sonnet-4-5 \
  --prompt-file phase1-core.md

# Phase 2: Add tests with GPT-4o
patchpal-sandbox --env-file .env -- autopilot \
  --model openai/gpt-4o \
  --prompt-file phase2-tests.md

# Phase 3: Documentation with local model
patchpal-sandbox --host-network -- autopilot \
  --model ollama_chat/qwen2.5-coder:32b \
  --prompt-file phase3-docs.md

Secure Autopilot with Network Restrictions

# Maximum security: network isolation + autopilot
patchpal-sandbox \
  --restrict-network \
  --env-file .env \
  --memory 4g \
  -- autopilot \
  --model anthropic/claude-sonnet-4-5 \
  --prompt-file secure-task.md \
  --max-iterations 20

Debugging Inside Container

# Start shell inside container with model pre-configured
patchpal-sandbox --env-file .env --shell -- --model groq/llama-3.3-70b-versatile

# Inside container
$ pwd
/workspace

$ ls -la ~/.patchpal/tools/
# Your custom tools are here

$ echo $PATCHPAL_MODEL
groq/llama-3.3-70b-versatile

$ patchpal
# Runs with the pre-configured model automatically

Tip: When you provide --model after --, it's automatically set as the PATCHPAL_MODEL environment variable.

Using Different Providers

# Google Gemini
patchpal-sandbox --env-file .env -- autopilot \
  --model gemini/gemini-2.0-flash-exp \
  --prompt-file task.md

# Groq (fast inference)
patchpal-sandbox --env-file .env -- autopilot \
  --model groq/llama-3.3-70b-versatile \
  --prompt-file task.md

# Azure OpenAI
patchpal-sandbox --env-file .env.azure -- autopilot \
  --model azure/gpt-4o \
  --prompt-file task.md

Learn More