> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt > Use this file to discover all available pages before exploring further. # Sandbox Tool > Sandboxed execution environment for security # Sandbox Tool The sandbox provides an isolated execution environment for running untrusted code and commands securely. ## Overview Sandboxing protects your system by: * **Isolating execution:** Commands run in separate container * **Limiting access:** Restricted file system and network access * **Resource control:** CPU and memory limits * **Clean environment:** Fresh state for each session ## Supported Providers ### Docker **Status:** Recommended for most users **Requirements:** * Docker Desktop or Docker Engine * Sufficient disk space for container image **Setup:** ```bash theme={null} # Enable Docker sandbox export QWEN_SANDBOX=docker # Build sandbox image npm run build:sandbox # Start Qwen Code qwen-code ``` ### Podman **Status:** Alternative to Docker **Requirements:** * Podman installed and configured * Rootless mode supported **Setup:** ```bash theme={null} # Enable Podman sandbox export QWEN_SANDBOX=podman # Start Qwen Code qwen-code ``` ### macOS Seatbelt **Status:** macOS native sandboxing **Requirements:** * macOS operating system * System Integrity Protection enabled **Setup:** ```bash theme={null} # Enable macOS sandbox export QWEN_SANDBOX=macos # Start Qwen Code qwen-code ``` ### No Sandbox **Status:** Not recommended (development only) **Setup:** ```bash theme={null} # Disable sandboxing export QWEN_SANDBOX=false # Start Qwen Code qwen-code ``` ⚠️ **Warning:** Only use when necessary. Commands execute with full system access. ## Configuration ### Environment Variable The primary configuration method: ```bash theme={null} # In ~/.bashrc, ~/.zshrc, or ~/.env export QWEN_SANDBOX=docker # or podman, macos, false ``` ### Settings File Configure in `settings.json`: ```json theme={null} { "tools": { "sandbox": { "enabled": true, "provider": "docker", "image": "ghcr.io/qwenlm/qwen-code:latest" } } } ``` ### Build Configuration **Default Image:** ``` ghcr.io/qwenlm/qwen-code: ``` **Custom Image:** See "Customizing the Sandbox" section below. ## How It Works ### Execution Flow ``` User Request │ v Shell Tool │ ├─ Is sandbox enabled? │ ├─ Yes: Route to sandbox │ │ │ v │ Sandbox Container │ ├─ Mount project directory │ ├─ Execute command │ ├─ Capture output │ └─ Return result │ └─ No: Execute directly │ v Host System ``` ### Container Lifecycle 1. **Session Start:** * Pull/build sandbox image * Start container * Mount project directory * Set up environment 2. **Command Execution:** * Send command to container * Execute in isolated environment * Stream output back to CLI * Handle errors and timeouts 3. **Session End:** * Stop container * Clean up resources * Preserve project changes ## Customizing the Sandbox ### Custom Dockerfile **Note:** This requires working from the source code repository, not an npm-installed package. #### Requirements 1. Clone the Qwen Code repository: ```bash theme={null} git clone https://github.com/QwenLM/qwen-code.git cd qwen-code ``` 2. Install dependencies: ```bash theme={null} npm install ``` 3. Build the project: ```bash theme={null} npm run build ``` 4. Link the CLI globally: ```bash theme={null} cd packages/cli npm link ``` #### Create Custom Dockerfile Create `.qwen/sandbox.Dockerfile` in your project: ```dockerfile theme={null} # Base on official Qwen sandbox image FROM ghcr.io/qwenlm/qwen-code:sha-570ec43 # Add extra tools RUN apt-get update && apt-get install -y \ git \ python3 \ python3-pip \ ripgrep \ jq \ && rm -rf /var/lib/apt/lists/* # Install Python packages RUN pip3 install --no-cache-dir \ requests \ beautifulsoup4 # Add custom scripts COPY scripts/ /usr/local/bin/ RUN chmod +x /usr/local/bin/*.sh # Set working directory WORKDIR /workspace ``` #### Build Custom Image From your project root: ```bash theme={null} QWEN_SANDBOX=docker BUILD_SANDBOX=1 qwen -s ``` This builds a project-specific image based on your Dockerfile. #### Verify Custom Image ```bash theme={null} # Start Qwen Code qwen-code # Test custom tool /shell git --version /shell python3 --version /shell rg --version ``` ### Restore Official CLI After testing custom sandbox: ```bash theme={null} # Unlink source build cd packages/cli npm unlink # Verify removal which qwen # Should show "not found" # Reinstall official version npm install -g @qwen-code/qwen-code # Verify qwen-code --version ``` ## Sandbox Limitations ### File System **Accessible:** * Project directory (mounted read-write) * Temp directory within container * Standard Unix paths **Not Accessible:** * Home directory outside project * System directories * Other projects ### Network **Default:** * Outbound connections allowed * No inbound connections * DNS resolution available **Can be restricted further** with custom configuration. ### Performance **Overhead:** * Container startup: \~1-2 seconds * Command execution: Minimal (less than 100ms) * File I/O: Slightly slower than native **Optimization:** * Keep container running between commands * Use `.dockerignore` to exclude large files * Cache package installations in image ## Security Benefits ### Isolation ✅ **Protected:** * System files * Other projects * User data * Network resources ✅ **Contained:** * Malicious scripts * Unexpected side effects * Resource consumption * File system modifications ### Use Cases **When to use sandbox:** 1. **Untrusted code:** ```bash theme={null} # Run downloaded script safely ./unknown-script.sh ``` 2. **Experimental commands:** ```bash theme={null} # Test potentially dangerous operation rm -rf suspicious-directory/ ``` 3. **Package installation:** ```bash theme={null} # Install untrusted package npm install unknown-package ``` 4. **Build processes:** ```bash theme={null} # Run complex build make all ``` **When sandbox isn't needed:** 1. Trusted, well-known commands (`git status`, `ls`) 2. Simple file operations 3. Built-in tools (read\_file, write\_file) 4. Development on personal projects ## Troubleshooting ### Image Build Fails **Error:** `Failed to build sandbox image` **Solutions:** 1. Check Docker/Podman is running 2. Verify internet connectivity 3. Check disk space: `df -h` 4. Clear Docker cache: `docker system prune` 5. Retry build: `npm run build:sandbox` ### Container Won't Start **Error:** `Container failed to start` **Solutions:** 1. Check Docker daemon: `docker ps` 2. Review logs: `docker logs ` 3. Restart Docker Desktop 4. Check resource limits ### Permission Errors **Error:** `Permission denied in sandbox` **Solutions:** 1. Check file permissions in project 2. Verify mount points 3. Use rootless container if possible 4. Check SELinux/AppArmor policies ### Performance Issues **Symptoms:** Slow command execution **Solutions:** 1. Check Docker resource allocation 2. Reduce mounted directory size 3. Use `.dockerignore`: ``` node_modules/ .git/ dist/ *.log ``` 4. Increase Docker Desktop resources ### Network Issues **Error:** `Network request failed in sandbox` **Solutions:** 1. Check Docker network mode 2. Verify DNS resolution: `docker run alpine nslookup google.com` 3. Check firewall rules 4. Test with `--network host` (temporary) ## Best Practices ### 1. Keep Images Updated ```bash theme={null} # Pull latest official image docker pull ghcr.io/qwenlm/qwen-code:latest # Rebuild sandbox npm run build:sandbox ``` ### 2. Optimize Image Size ```dockerfile theme={null} # Multi-stage build FROM node:20 AS builder WORKDIR /build COPY package*.json ./ RUN npm ci --production FROM ghcr.io/qwenlm/qwen-code:latest COPY --from=builder /build/node_modules ./node_modules ``` ### 3. Cache Dependencies ```dockerfile theme={null} # Cache apt packages RUN --mount=type=cache,target=/var/cache/apt \ apt-get update && apt-get install -y git # Cache npm packages RUN --mount=type=cache,target=/root/.npm \ npm install -g typescript ``` ### 4. Use .dockerignore ``` # .dockerignore node_modules/ .git/ dist/ build/ *.log .env ``` ### 5. Monitor Resources ```bash theme={null} # Check container resource usage docker stats # Check disk usage docker system df ``` ## Configuration Reference ### Full Settings ```json theme={null} { "tools": { "sandbox": { "enabled": boolean, // Enable sandboxing "provider": string, // "docker", "podman", "macos", "false" "image": string, // Container image "dockerfile": string, // Custom Dockerfile path "buildArgs": object, // Docker build arguments "containerOptions": { "memory": string, // Memory limit (e.g., "2g") "cpus": number, // CPU count "timeout": number, // Timeout in ms "network": string, // Network mode } } } } ``` ### Environment Variables ```bash theme={null} QWEN_SANDBOX=docker # Sandbox provider BUILD_SANDBOX=1 # Trigger sandbox build DOCKER_HOST=unix:///var/run/docker.sock # Docker socket ``` ## Implementation **Key Files:** * `scripts/build_sandbox.js` - Build script * `Dockerfile` - Sandbox image definition * `packages/core/src/services/shellExecutionService.ts` - Execution routing ### Shell Execution Service ```typescript theme={null} export class ShellExecutionService { async executeCommand( command: string, options: ShellExecutionConfig, ): Promise { if (this.config.isSandboxEnabled()) { return this.executeSandboxed(command, options); } return this.executeDirect(command, options); } private async executeSandboxed( command: string, options: ShellExecutionConfig, ): Promise { const containerCmd = [ 'docker', 'exec', '-i', '-w', '/workspace', this.containerId, 'bash', '-c', command, ]; return this.spawn(containerCmd, options); } } ``` ## Next Steps * [Shell Tool](./shell.mdx) - Shell command execution * [Development Setup](../development-setup.mdx) - Setting up sandbox for development * [Configuration System](../configuration-system.mdx) - Advanced configuration