sandbox

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "name": "write_file",
  "arguments": {
    "file_path": "/home/user/output.txt",
    "content": "Hello, Sandbox!"
  }
}

Example - HTML file:

{
  "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:

{
  "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:

{
  "name": "download_attachment",
  "arguments": {
    "attachment_url": "/api/attachments/123/download"
  }
}

Tool Selection Guide

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

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

Scenario 2: Install System Packages (AlmaLinux)

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

Scenario 3: File Management

// 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

{
  "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.

// 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:

{
  "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"

{
  "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:

{
  "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:

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))
"