---
name: wecode-ai/sandbox-environment
source: https://app.decimal.ai/s/wecode-ai-sandbox-environment@2/SKILL.md
source_sha256: a83fd35fe82f
---

# Sandbox Environment

Execute code, commands, and complex tasks securely in isolated Docker containers running **AlmaLinux 9.4**.

## Core Capabilities

The sandbox environment provides fully isolated execution spaces with:

1. **Command Execution** - Run shell commands, scripts, and programs
2. **File Operations** - Read/write files, browse directories, manage filesystems
3. **Code Execution** - Safely execute and test code
4. **Claude AI Tasks** - Available for advanced use cases when explicitly requested by users
5. **Attachment Upload/Download** - Upload generated files to Wegent for user download, or download user attachments for processing

## When to Use

Use this skill when you need to:

- ✅ Execute shell commands or scripts
- ✅ Run and test code
- ✅ Read, write, or manage files
- ✅ Perform multi-step programming tasks
- ✅ Git operations (clone, commit, push, etc.)
- ✅ Require isolated environment for safety

**Note**: The `sub_claude_agent` tool should only be used when the user explicitly requests Claude AI assistance (e.g., "use Claude to generate...", "ask Claude to create...").

## Available Tools

### Command Execution

#### `exec`
Execute shell commands in the sandbox environment.

**Use Cases:**
- Run single commands or scripts
- Directory operations (create, delete, move)
- Install dependencies, run tests
- View system information

**Parameters:**
- `command` (required): Shell command to execute
- `working_dir` (optional): Working directory path
- `timeout` (optional): Timeout in seconds

**Example:**
```json
{
  "name": "exec",
  "arguments": {
    "command": "python script.py --arg value",
    "working_dir": "/home/user/project"
  }
}
```

---

#### `sub_claude_agent`
Run Claude AI to execute complex tasks in the sandbox.

**⚠️ IMPORTANT**: This tool should **only be used when the user explicitly requests it**. Do not use this tool automatically or as a default option.

**Use Cases:**
- When user explicitly asks to use Claude (e.g., "use Claude to generate...", "ask Claude to create...")
- Generate presentations and Word documents (when specifically requested)
- Create code projects (when specifically requested)
- Complex multi-step programming tasks (when specifically requested)

**Parameters:**
- `prompt` (required): Task description for Claude
- `allowed_tools` (optional): List of tools Claude can use
- `append_system_prompt` (optional): Additional system prompt
- `timeout` (optional): Timeout in seconds (minimum: 600 seconds / 10 minutes, default: 1800 seconds / 30 minutes)

**Features:**
- ⚡ Real-time streaming output
- 🔧 Customizable tool sets
- 📊 WebSocket progress updates

**Example:**
```json
{
  "name": "sub_claude_agent",
  "arguments": {
    "prompt": "Create a 5-page presentation about the history of artificial intelligence",
    "allowed_tools": "Edit,Write,Bash(*),skills,Read"
  }
}
```

---

### File Operations

#### `list_files`
List files and subdirectories in a directory.

**Parameters:**
- `path` (required): Directory path
- `depth` (optional): Recursion depth, default 1

**Returns:**
- File metadata including name, size, permissions, modification time

**Example:**
```json
{
  "name": "list_files",
  "arguments": {
    "path": "/home/user/project",
    "depth": 2
  }
}
```

---

#### `read_file`
Read file contents.

**Parameters:**
- `file_path` (required): File path to read

**Limits:**
- Maximum file size: 1MB (configurable)

**Example:**
```json
{
  "name": "read_file",
  "arguments": {
    "file_path": "/home/user/config.json"
  }
}
```

---

#### `write_file`
Write content to a file.

⚠️ **IMPORTANT**: Both `file_path` AND `content` are **REQUIRED** parameters. You must always provide the content to write.

**Parameters:**
- `file_path` (REQUIRED): File path to write
- `content` (REQUIRED): Content to write (MUST be provided, cannot be omitted)
- `format` (optional): Content format - 'text' (default) or 'bytes' (base64-encoded)
- `create_dirs` (optional): Auto-create parent directories (default: True)

**Features:**
- Automatically creates parent directories
- Maximum file size: 10MB (configurable)

**Example - Text file:**
```json
{
  "name": "write_file",
  "arguments": {
    "file_path": "/home/user/output.txt",
    "content": "Hello, Sandbox!"
  }
}
```

**Example - HTML file:**
```json
{
  "name": "write_file",
  "arguments": {
    "file_path": "/home/user/index.html",
    "content": "<!DOCTYPE html><html><head><title>Test</title></head><body><h1>Hello</h1></body></html>"
  }
}
```

---

### Attachment Operations

#### `upload_attachment`
Upload a file from sandbox to Wegent and get a download URL for users.

**Use Cases:**
- Upload generated documents (PDF, Word, etc.) for user download
- Share files created in the sandbox with users
- Export results from sandbox to Wegent storage
- User can not access file directly, you MUST use upload_attachment tool for sending file to user.

**Parameters:**
- `file_path` (required): Path to the file in sandbox to upload
- `timeout_seconds` (optional): Upload timeout in seconds (default: 300)

**Returns:**
- `success`: Whether the upload succeeded
- `attachment_id`: ID of the uploaded attachment
- `filename`: Name of the uploaded file
- `file_size`: Size of the file in bytes
- `mime_type`: MIME type of the file
- `download_url`: Relative URL for downloading (e.g., `/api/attachments/123/download`)

**Limits:**
- Maximum file size: 100MB

**Example:**
```json
{
  "name": "upload_attachment",
  "arguments": {
    "file_path": "/home/user/documents/report.pdf"
  }
}
```

**After Upload - Presenting to User:**
After a successful upload, present the download link to the user:
```
Document generation completed!

📄 **report.pdf**

[Click to Download](/api/attachments/123/download)
```

---

#### `download_attachment`
Download a file from Wegent attachment URL to sandbox for processing.

**Use Cases:**
- Download user-uploaded attachments for processing
- Retrieve files from Wegent storage into the sandbox

**Parameters:**
- `attachment_url` (required): Wegent attachment URL (e.g., `/api/attachments/123/download`)
- `timeout_seconds` (optional): Download timeout in seconds (default: 300)

The tool resolves the attachment filename and owning subtask from Wegent, then
saves it to the canonical task attachment directory:
`/home/user/{task_id}:executor:attachments/{subtask_id}/{filename}`.

**Returns:**
- `success`: Whether the download succeeded
- `file_path`: Full path to the downloaded file in sandbox
- `file_size`: Size of the downloaded file in bytes

**Example:**
```json
{
  "name": "download_attachment",
  "arguments": {
    "attachment_url": "/api/attachments/123/download"
  }
}
```

---

## Tool Selection Guide

| Task Type | Recommended Tool | Reason |
|-----------|-----------------|--------|
| Execute commands or scripts | `exec` | Fast execution, no overhead |
| Create/delete directories | `exec` | Use `mkdir -p` or `rm -rf` directly |
| Read files | `read_file` | Better error handling and size validation |
| Write files | `write_file` | Auto directory creation, size validation |
| Browse directories | `list_files` | Structured output with metadata |
| Upload files for user download | `upload_attachment` | Get download URL for user-facing files |
| Download attachments | `download_attachment` | Retrieve Wegent attachments into sandbox |
| Complex tasks with Claude | `sub_claude_agent` | **Only when user explicitly requests** |

**Important**: Always prefer `exec` for standard operations. Only use `sub_claude_agent` when the user specifically asks for Claude AI assistance.

---

## Usage Examples

### Scenario 1: Run Python Script

```json
{
  "name": "exec",
  "arguments": {
    "command": "cd /home/user && python -m pip install requests && python app.py"
  }
}
```

### Scenario 2: Install System Packages (AlmaLinux)

```json
{
  "name": "exec",
  "arguments": {
    "command": "dnf install -y gcc make && gcc --version"
  }
}
```

### Scenario 3: File Management

```json
// 1. List files
{
  "name": "list_files",
  "arguments": {
    "path": "/home/user"
  }
}

// 2. Read file
{
  "name": "read_file",
  "arguments": {
    "file_path": "/home/user/data.json"
  }
}

// 3. Write file
{
  "name": "write_file",
  "arguments": {
    "file_path": "/home/user/result.txt",
    "content": "Processing complete: Success"
  }
}
```

### Scenario 4: Git Operations

```json
{
  "name": "exec",
  "arguments": {
    "command": "git clone https://github.com/user/repo.git && cd repo && git checkout -b feature"
  }
}
```

### Scenario 5: Creating ZIP Files

⚠️ **`zip` is not pre-installed.** Always run `dnf install -y zip` before using it.

⚠️ **Always use English or pinyin folder names as the ZIP root directory.** The `zip` command does not set the ZIP UTF-8 flag, so Windows decodes Chinese names using CP437, resulting in garbled folders that appear empty.

```json
// Step 1: Install zip
{
  "name": "exec",
  "arguments": {
    "command": "dnf install -y zip"
  }
}

// Step 2: Create ZIP with English folder name (recommended)
{
  "name": "exec",
  "arguments": {
    "command": "zip -r 'my-skill.zip' 'my-skill/'"
  }
}
```

**If the user explicitly requires a Chinese folder name**, use Python's `zipfile` module instead — it automatically sets the UTF-8 flag so Windows can decode Chinese names correctly:

```json
{
  "name": "exec",
  "arguments": {
    "command": "python3 -c \"\nimport zipfile, os\nfolder = '中文名称'\nwith zipfile.ZipFile(folder + '.zip', 'w', zipfile.ZIP_DEFLATED) as zf:\n    for root, dirs, files in os.walk(folder):\n        for f in files:\n            zf.write(os.path.join(root, f))\n\""
  }
}
```

### Scenario 6: Using Claude (Only When Explicitly Requested)

**Example user request**: "Please use Claude to generate a presentation about AI"

```json
{
  "name": "sub_claude_agent",
  "arguments": {
    "prompt": "Create a 5-page presentation about the history of artificial intelligence"
  }
}
```

**Note**: This scenario should only be used when the user explicitly asks for Claude assistance.

---

## Sandbox Environment

### System Environment
- **Operating System**: AlmaLinux 9.4 (RHEL 9 compatible)
- **Architecture**: x86_64
- **Package Manager**: dnf/yum
- **Init System**: systemd
- **Python**: 3.12+ (pre-installed)
- **Shell**: bash

### Lifecycle
- New sandbox created on first tool call
- Subsequent calls in the same session reuse the sandbox
- Sandbox persists for 30 minutes by default
- Files persist within the session
- Each sandbox runs in an isolated Docker container

### Resource Limits
- **Read file limit**: 1MB (configurable)
- **Write file limit**: 10MB (configurable)
- **Upload file limit**: 100MB (configurable)
- **Command timeout**: 300 seconds (5 minutes)
- **Claude timeout**: 1800 seconds (30 minutes, minimum: 600 seconds / 10 minutes)
- **Total task timeout**: 7200 seconds (2 hours)

### Security Features
- ✅ Fully isolated Docker containers (AlmaLinux 9.4)
- ✅ Network access control
- ✅ Resource constraints
- ✅ Automatic cleanup

---

## Configuration Options

### Shell Types
- **ClaudeCode** (default): For code generation, Git operations, multi-step programming
- **Agno**: For team collaboration and multi-agent coordination

### Claude Tool Configuration
Control Claude's available tools via the `allowed_tools` parameter:

```json
{
  "allowed_tools": "Edit,Write,MultiEdit,Bash(*),skills,Read,Glob,Grep,LS"
}
```

- `Bash(*)`: Allow all Bash commands
- Restrict tools as needed for enhanced security or task focus

---

## Best Practices

1. **Clear Task Descriptions** - Provide detailed instructions and expected outcomes
2. **Use Absolute Paths** - Avoid path ambiguity
3. **Choose the Right Tool** - Refer to the tool selection guide
4. **Check Return Results** - Verify the `success` field
5. **Mind Size Limits** - File read/write operations have size constraints
6. **Prefer exec** - Use for most tasks; only use `sub_claude_agent` when user explicitly requests Claude assistance
7. **ZIP Encoding** - Install `zip` first with `dnf install -y zip`; always use English/pinyin folder names for cross-platform compatibility; if Chinese names are required, use Python's `zipfile` module (it sets the UTF-8 flag correctly, preventing garbled names on Windows)

---

## Troubleshooting

### Sandbox Creation Failed
**Cause**: Executor Manager unavailable
**Solution**: Check service status and configuration

### File Not Found
**Cause**: Incorrect path or file doesn't exist
**Solution**: Use absolute paths, verify with `list_files` first

### Command Timeout
**Cause**: Task execution takes too long
**Solution**: Increase timeout setting or split into smaller tasks

### File Too Large
**Cause**: Exceeds size limit (1MB read / 10MB write)
**Solution**: Process in chunks or adjust configuration

### Permission Denied
**Cause**: Insufficient file permissions
**Solution**: Check file paths and permission settings

### ZIP Folder Appears Empty or Garbled on Windows
**Cause**: The `zip` command stores filenames as raw bytes without setting the ZIP UTF-8 flag (bit 11). Windows decodes them using CP437, turning Chinese folder names into garbled text, making contents inaccessible.
**Solution**: Use English/pinyin folder names with the `zip` command. If Chinese names are required, use Python's `zipfile` module — it sets the UTF-8 flag automatically:
```bash
python3 -c "
import zipfile, os
folder = '中文名称'
with zipfile.ZipFile(folder + '.zip', 'w', zipfile.ZIP_DEFLATED) as zf:
    for root, dirs, files in os.walk(folder):
        for f in files:
            zf.write(os.path.join(root, f))
"