feat: Adjust the directory structure

docs/features/sandbox.md

@@ -0,0 +1,157 @@
+# Sandboxing in Qwen Code
+
+This document provides a guide to sandboxing in Qwen Code, including prerequisites, quickstart, and configuration.
+
+## Prerequisites
+
+Before using sandboxing, you need to install and set up Qwen Code:
+
+```bash
+npm install -g @qwen-code/qwen-code
+```
+
+To verify the installation
+
+```bash
+qwen --version
+```
+
+## Overview of sandboxing
+
+Sandboxing isolates potentially dangerous operations (such as shell commands or file modifications) from your host system, providing a security barrier between AI operations and your environment.
+
+The benefits of sandboxing include:
+
+- **Security**: Prevent accidental system damage or data loss.
+- **Isolation**: Limit file system access to project directory.
+- **Consistency**: Ensure reproducible environments across different systems.
+- **Safety**: Reduce risk when working with untrusted code or experimental commands.
+
+## Sandboxing methods
+
+Your ideal method of sandboxing may differ depending on your platform and your preferred container solution.
+
+### 1. macOS Seatbelt (macOS only)
+
+Lightweight, built-in sandboxing using `sandbox-exec`.
+
+**Default profile**: `permissive-open` - restricts writes outside project directory but allows most other operations.
+
+### 2. Container-based (Docker/Podman)
+
+Cross-platform sandboxing with complete process isolation.
+
+**Note**: Requires building the sandbox image locally or using a published image from your organization's registry.
+
+## Quickstart
+
+```bash
+# Enable sandboxing with command flag
+qwen -s -p "analyze the code structure"
+
+# Use environment variable
+export GEMINI_SANDBOX=true
+qwen -p "run the test suite"
+
+# Configure in settings.json
+{
+  "tools": {
+    "sandbox": "docker"
+  }
+}
+```
+
+## Configuration
+
+### Enable sandboxing (in order of precedence)
+
+1. **Command flag**: `-s` or `--sandbox`
+2. **Environment variable**: `GEMINI_SANDBOX=true|docker|podman|sandbox-exec`
+3. **Settings file**: `"sandbox": true` in the `tools` object of your `settings.json` file (e.g., `{"tools": {"sandbox": true}}`).
+
+### macOS Seatbelt profiles
+
+Built-in profiles (set via `SEATBELT_PROFILE` env var):
+
+- `permissive-open` (default): Write restrictions, network allowed
+- `permissive-closed`: Write restrictions, no network
+- `permissive-proxied`: Write restrictions, network via proxy
+- `restrictive-open`: Strict restrictions, network allowed
+- `restrictive-closed`: Maximum restrictions
+
+### Custom Sandbox Flags
+
+For container-based sandboxing, you can inject custom flags into the `docker` or `podman` command using the `SANDBOX_FLAGS` environment variable. This is useful for advanced configurations, such as disabling security features for specific use cases.
+
+**Example (Podman)**:
+
+To disable SELinux labeling for volume mounts, you can set the following:
+
+```bash
+export SANDBOX_FLAGS="--security-opt label=disable"
+```
+
+Multiple flags can be provided as a space-separated string:
+
+```bash
+export SANDBOX_FLAGS="--flag1 --flag2=value"
+```
+
+## Linux UID/GID handling
+
+The sandbox automatically handles user permissions on Linux. Override these permissions with:
+
+```bash
+export SANDBOX_SET_UID_GID=true   # Force host UID/GID
+export SANDBOX_SET_UID_GID=false  # Disable UID/GID mapping
+```
+
+## Troubleshooting
+
+### Common issues
+
+**"Operation not permitted"**
+
+- Operation requires access outside sandbox.
+- Try more permissive profile or add mount points.
+
+**Missing commands**
+
+- Add to custom Dockerfile.
+- Install via `sandbox.bashrc`.
+
+**Network issues**
+
+- Check sandbox profile allows network.
+- Verify proxy configuration.
+
+### Debug mode
+
+```bash
+DEBUG=1 qwen -s -p "debug command"
+```
+
+**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect the CLI due to automatic exclusion. Use `.qwen/.env` files for Qwen Code-specific debug settings.
+
+### Inspect sandbox
+
+```bash
+# Check environment
+qwen -s -p "run shell command: env | grep SANDBOX"
+
+# List mounts
+qwen -s -p "run shell command: mount | grep workspace"
+```
+
+## Security notes
+
+- Sandboxing reduces but doesn't eliminate all risks.
+- Use the most restrictive profile that allows your work.
+- Container overhead is minimal after first build.
+- GUI applications may not work in sandboxes.
+
+## Related documentation
+
+- [Configuration](./cli/configuration.md): Full configuration options.
+- [Commands](./cli/commands.md): Available commands.
+- [Troubleshooting](./troubleshooting.md): General troubleshooting.