recoder-code/SANDBOX_QUICK_REFERENCE.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

# Sandbox Quick Reference Card

## Answer to Your Question: "Why no sandbox? Can we have sandbox?"

**YES! You already have sandbox!** 🎉

The "no sandbox" message means sandbox mode is **disabled** (the default), not that it's unavailable. Recoder Code has full sandbox support built-in from the Qwen Code foundation.

## Enable Sandbox in 3 Seconds

```bash
# Method 1: Docker (works everywhere)
export RECODER_SANDBOX=docker
recoder-code

# Method 2: macOS Seatbelt (macOS only, no Docker needed)
export RECODER_SANDBOX=sandbox-exec
recoder-code
```

## Visual Indicator

### Without Sandbox (Current)
```
💻 Interactive Mode (type /help)
```

### With Sandbox (After enabling)
```
🔒 docker                  # Docker sandbox active
🔒 macOS Seatbelt (...)    # Seatbelt sandbox active
```

## One-Line Commands

```bash
# Enable Docker sandbox permanently
echo 'export RECODER_SANDBOX=docker' >> ~/.zshrc

# Enable for this session only
RECODER_SANDBOX=docker recoder-code

# Check if sandbox is active (inside Recoder Code)
!echo $SANDBOX
```

## What Sandbox Does

| Feature | Without Sandbox | With Sandbox |
|---------|----------------|--------------|
| Code execution | On your system | In container |
| File access | Full system | Project dir only |
| Network access | Full | Controlled |
| Security | Trust-based | Isolated |
| Performance | Fastest | Minimal overhead |

## Files Created/Updated

1. **SANDBOX_SETUP_GUIDE.md** - Complete 300+ line guide
2. **SANDBOX_FEATURE_SUMMARY.md** - Technical overview
3. **README.md** - Added sandbox section
4. **sandboxConfig.ts** - Support RECODER_* env vars
5. **sandbox.ts** - Support RECODER_* env vars

## Environment Variables

### New (Recoder Code)
- `RECODER_SANDBOX` - Enable sandbox (docker|podman|sandbox-exec)
- `RECODER_SANDBOX_IMAGE` - Custom Docker image
- `RECODER_SANDBOX_PROXY_COMMAND` - Proxy command

### Legacy (Still work)
- `GEMINI_SANDBOX`
- `GEMINI_SANDBOX_IMAGE`
- `GEMINI_SANDBOX_PROXY_COMMAND`

## Quick Tests

### Test 1: Check Docker availability
```bash
docker --version
```

### Test 2: Enable sandbox and check status
```bash
export RECODER_SANDBOX=docker
recoder-code
# Look at footer: should show 🔒 docker
```

### Test 3: Verify isolation (inside Recoder Code)
```bash
> !whoami
# Without sandbox: your username
# With sandbox: node or gemini
```

## Common Use Cases

### Development (No sandbox needed)
```bash
recoder-code
```

### Testing AI code (Use sandbox)
```bash
export RECODER_SANDBOX=docker
recoder-code "generate a web server"
```

### Production/CI (Use sandbox)
```bash
export RECODER_SANDBOX=docker
recoder-code --batch < commands.txt
```

## System Requirements

| Sandbox Type | Requirements |
|-------------|--------------|
| None | Just Node.js |
| Docker | Docker Desktop/Engine |
| Podman | Podman installed |
| macOS Seatbelt | macOS 10.5+ (built-in) |

## Troubleshooting One-Liners

```bash
# Docker not running?
open -a Docker  # macOS

# Permission denied?
sudo usermod -aG docker $USER && newgrp docker  # Linux

# Image missing?
docker pull node:20-alpine
```

## Next Steps

1. **Try it now:**
   ```bash
   export RECODER_SANDBOX=docker
   recoder-code
   ```

2. **Read full guide:** Open `SANDBOX_SETUP_GUIDE.md`

3. **Customize:** Create `.recoder/sandbox.Dockerfile` for custom environment

4. **Share:** Push to GitHub so others can use it

## Summary

✅ Sandbox **is available** in Recoder Code
✅ It's **optional** (disabled by default for ease of use)
✅ Enable with **one environment variable**
✅ Works with **Docker, Podman, or macOS Seatbelt**
✅ Provides **security isolation** for AI-generated code
✅ Documentation **added** (3 new files)
✅ Code **updated** to support RECODER_* variables
✅ Changes **committed** to git

The "no sandbox" message simply means "sandbox is not currently active", not "sandbox is unavailable". You now have complete control over sandbox mode!

---

**Quick Start:** `export RECODER_SANDBOX=docker && recoder-code`