recoder-code/SANDBOX_SETUP_GUIDE.md

🚀 Recoder Code - AI-powered CLI for developers. Chat with 40+ models (Claude, GPT-4, DeepSeek, Gemini, Qwen3) with tool calling support. Build projects, automate workflows. Free agentic models included! Features interactive mode, file operations, and opt

# Recoder Code Sandbox Setup Guide

## What is the Sandbox?

The sandbox feature provides **isolated execution** of commands and code, protecting your system from potentially harmful operations. When enabled, Recoder Code runs all shell commands and file operations inside a containerized environment.

## Benefits of Using Sandbox

1. **Security**: Isolates AI-generated code from your main system
2. **Reproducibility**: Consistent environment across different machines
3. **Safety**: Prevents accidental system-wide changes
4. **Clean testing**: Test code without affecting your development environment

## Current Status

You're seeing "no sandbox" in the footer because sandbox mode is **disabled by default**. Recoder Code supports three sandbox options:

1. **Docker** (Linux/macOS/Windows)
2. **Podman** (Linux/macOS alternative to Docker)
3. **macOS Seatbelt** (macOS only, lightweight sandboxing)

## Quick Setup

### Option 1: Docker Sandbox (Recommended for most users)

#### Prerequisites
```bash
# Install Docker Desktop (macOS/Windows)
# Or install Docker Engine (Linux)
# Visit: https://docs.docker.com/get-docker/
```

#### Enable Sandbox
```bash
# Method 1: Environment variable (temporary)
export RECODER_SANDBOX=docker

# Method 2: In .env file (permanent)
echo "RECODER_SANDBOX=docker" >> ~/.recoder/.env

# Method 3: Command line flag
recoder-code --sandbox docker
```

#### Specify Custom Image (Optional)
```bash
# Use a specific Docker image
export RECODER_SANDBOX_IMAGE=node:20-alpine

# Or in package.json config
{
  "config": {
    "sandboxImageUri": "node:20-alpine"
  }
}
```

### Option 2: macOS Seatbelt (macOS only, lightweight)

macOS Seatbelt provides lightweight sandboxing without Docker:

```bash
# Enable seatbelt sandbox
export RECODER_SANDBOX=sandbox-exec

# Choose a profile (optional, default: permissive-open)
export SEATBELT_PROFILE=restrictive-open

# Run Recoder Code
recoder-code
```

**Available Profiles:**
- `permissive-open` - Network access allowed (default)
- `permissive-closed` - No network access
- `permissive-proxied` - Network through proxy only
- `restrictive-open` - Limited file access + network
- `restrictive-closed` - Limited file access, no network
- `restrictive-proxied` - Limited file access + proxy

### Option 3: Podman (Docker alternative)

```bash
# Install Podman first
# macOS: brew install podman
# Linux: sudo apt install podman (or use your distro's package manager)

# Enable Podman sandbox
export RECODER_SANDBOX=podman

# Run Recoder Code
recoder-code
```

## Configuration Options

### Environment Variables

```bash
# Core sandbox settings
RECODER_SANDBOX=docker|podman|sandbox-exec|false   # Sandbox type
RECODER_SANDBOX_IMAGE=image:tag                    # Container image
SANDBOX=container-name                              # Inside sandbox (auto-set)

# Advanced settings
SANDBOX_PORTS=8080,3000                            # Expose ports
SANDBOX_FLAGS="--memory=2g --cpus=2"               # Custom Docker flags
SANDBOX_MOUNTS=/path/to/mount:/container/path:ro   # Additional mounts
SANDBOX_ENV="KEY1=value1,KEY2=value2"              # Extra env vars
SANDBOX_SET_UID_GID=1                              # Use host UID/GID (Linux)

# Seatbelt-specific (macOS)
SEATBELT_PROFILE=permissive-open                   # Seatbelt profile

# Proxy settings (for restricted networks)
RECODER_SANDBOX_PROXY_COMMAND="mitmproxy -p 8877"  # Proxy command
HTTPS_PROXY=http://localhost:8877                   # Proxy URL
```

### Settings File Configuration

Add to `~/.recoder/settings.json`:

```json
{
  "tools": {
    "sandbox": "docker"
  }
}
```

Or use `recoder-code --sandbox docker` when starting.

## Verifying Sandbox is Active

When sandbox is enabled, you'll see in the footer:

```
🔒 docker-node-20          # Docker/Podman sandbox active
🔒 macOS Seatbelt (...)    # macOS Seatbelt active
💻 Interactive Mode        # No sandbox (current state)
```

You can also check with:
```bash
# Inside Recoder Code, run:
!echo $SANDBOX

# If output is empty, no sandbox
# If output shows container name, sandbox is active
```

## Troubleshooting

### Docker Daemon Not Running
```
Error: Cannot connect to Docker daemon
Solution: Start Docker Desktop or Docker service
```

### Image Not Found
```
Error: Sandbox image 'image:tag' is missing
Solution: Pull the image manually or let Recoder Code pull it
docker pull node:20-alpine
```

### Permission Issues (Linux)
```
Error: Permission denied
Solution: Add your user to docker group
sudo usermod -aG docker $USER
newgrp docker
```

### macOS Seatbelt Not Working
```
Error: Missing sandbox command 'sandbox-exec'
Solution: Seatbelt is built into macOS, check your macOS version
```

## Custom Sandbox Images

### Create a Custom Dockerfile

Create `.recoder/sandbox.Dockerfile`:

```dockerfile
FROM node:20-alpine

# Install additional tools
RUN apk add --no-cache \
    python3 \
    py3-pip \
    git \
    curl \
    vim

# Install Python packages
RUN pip3 install requests numpy pandas

# Set working directory
WORKDIR /workspace

# Custom entrypoint (optional)
CMD ["bash"]
```

### Build and Use Custom Image

```bash
# Set BUILD_SANDBOX to build on first run
export BUILD_SANDBOX=1
export RECODER_SANDBOX=docker
export RECODER_SANDBOX_IMAGE=recoder-code-custom

recoder-code
```

## Performance Considerations

### Sandbox Overhead
- **Docker/Podman**: ~100-500ms startup overhead, minimal runtime impact
- **macOS Seatbelt**: Negligible overhead, native performance

### When to Use Sandbox
- **Always**: When running untrusted or AI-generated code
- **Development**: Testing in clean environments
- **CI/CD**: Reproducible builds
- **Demos**: Safe demonstrations

### When Sandbox Might Not Be Needed
- **Trusted codebases**: Your own well-tested projects
- **Read-only operations**: Analyzing code without execution
- **Performance-critical**: High-frequency operations

## Integration with Recoder Code Features

### File Operations
All file read/write operations happen in the sandbox when enabled.

### Shell Commands
Every `!command` or shell execution runs inside the sandbox.

### Network Access
- Docker/Podman: Network access by default
- Seatbelt: Depends on profile (-open/-closed/-proxied)

### MCP Servers
MCP servers can run in or outside the sandbox depending on configuration.

## Next Steps

1. **Choose a sandbox method** based on your OS and requirements
2. **Set environment variables** or use command-line flags
3. **Test with a simple command** to verify sandbox is active
4. **Customize sandbox image** if you need additional tools

## Example Workflows

### Workflow 1: Basic Docker Sandbox
```bash
# Terminal 1: Start Docker Desktop (or ensure daemon is running)

# Terminal 2: Enable sandbox and run Recoder Code
export RECODER_SANDBOX=docker
recoder-code

# Inside Recoder Code:
> !whoami  # Should show 'node' or 'gemini' (container user)
> !hostname  # Should show container name
```

### Workflow 2: Custom Python Environment
```bash
# Create custom Dockerfile
mkdir -p ~/.recoder
cat > ~/.recoder/sandbox.Dockerfile << 'EOF'
FROM python:3.11-slim
RUN pip install numpy pandas scikit-learn jupyter
WORKDIR /workspace
EOF

# Build and use
export BUILD_SANDBOX=1
export RECODER_SANDBOX=docker
export RECODER_SANDBOX_IMAGE=recoder-python
recoder-code
```

### Workflow 3: macOS Lightweight Sandbox
```bash
# No Docker needed, uses native macOS Seatbelt
export RECODER_SANDBOX=sandbox-exec
export SEATBELT_PROFILE=restrictive-open
recoder-code

# Inside Recoder Code:
> !echo "Running in Seatbelt sandbox"
> !curl https://example.com  # Network access (if -open profile)
```

## FAQ

**Q: Will sandbox slow down Recoder Code?**
A: Docker/Podman adds ~100-500ms startup time. macOS Seatbelt has negligible impact.

**Q: Can I use multiple sandbox types?**
A: No, choose one sandbox method per session.

**Q: Do I need to rebuild the sandbox image when I update Recoder Code?**
A: Usually no, unless there are sandbox-specific changes. Set `BUILD_SANDBOX=1` to force rebuild.

**Q: Can I access files outside my project directory in sandbox?**
A: By default, only your project directory and `~/.recoder` are mounted. Use `SANDBOX_MOUNTS` for additional paths.

**Q: Is sandbox required for Recoder Code to work?**
A: No, sandbox is optional. Recoder Code works fine without it, but sandbox provides additional safety.

**Q: Can I expose ports from the sandbox?**
A: Yes, use `SANDBOX_PORTS=8080,3000` to expose specific ports.

## Support

- **Documentation**: See `/docs` in Recoder Code repository
- **Issues**: Create an issue on GitHub
- **Community**: Join discussions in the community forum

---

**Note**: Sandbox functionality is inherited from the Qwen Code base that Recoder Code was built upon. The code fully supports sandbox modes but requires explicit enablement.