Skip to main content

​
Overview

Sandbox tools provide file system operations and command execution capabilities in a secure, isolated environment. All operations use absolute paths and support both local and remote sandbox providers.

​
Virtual Path Mapping

The sandbox uses virtual paths that map to thread-specific directories:
  • /mnt/user-data/workspace/* → Thread workspace directory
  • /mnt/user-data/uploads/* → Thread uploads directory
  • /mnt/user-data/outputs/* → Thread outputs directory
For local sandboxes, these virtual paths are automatically replaced with actual filesystem paths.

​
bash

Execute a bash command in a Linux environment.

​
Parameters

​
description
str
required
Explain why you are running this command in short words. ALWAYS PROVIDE THIS PARAMETER FIRST.
​
command
str
required
The bash command to execute. Always use absolute paths for files and directories.

​
Usage

  • Use python to run Python code
  • Use pip install to install Python packages
  • Always use absolute paths in commands

​
Examples

# Run a Python script
bash(
    description="Run analysis script",
    command="python /mnt/user-data/workspace/analyze.py"
)

# Install dependencies
bash(
    description="Install required packages",
    command="pip install pandas numpy matplotlib"
)

# Git operations
bash(
    description="Commit changes",
    command="cd /mnt/user-data/workspace && git add . && git commit -m 'Update analysis'"
)

# Build and compile
bash(
    description="Build TypeScript project",
    command="cd /mnt/user-data/workspace && npm run build"
)

​
Return Type

Returns a string containing:
  • Command stdout/stderr output
  • Error messages if the command fails

​
ls

List the contents of a directory up to 2 levels deep in tree format.

​
Parameters

​
description
str
required
Explain why you are listing this directory in short words. ALWAYS PROVIDE THIS PARAMETER FIRST.
​
path
str
required
The absolute path to the directory to list.

​
Examples

# List workspace contents
ls(
    description="Check project structure",
    path="/mnt/user-data/workspace"
)

# List output files
ls(
    description="View generated files",
    path="/mnt/user-data/outputs"
)

​
Return Type

Returns a string containing:
  • Tree-formatted directory listing (up to 2 levels deep)
  • "(empty)" if directory is empty
  • Error message if directory not found or permission denied

​
read_file

Read the contents of a text file. Use this to examine source code, configuration files, logs, or any text-based file.

​
Parameters

​
description
str
required
Explain why you are reading this file in short words. ALWAYS PROVIDE THIS PARAMETER FIRST.
​
path
str
required
The absolute path to the file to read.
​
start_line
int
Optional starting line number (1-indexed, inclusive). Use with end_line to read a specific range.
​
end_line
int
Optional ending line number (1-indexed, inclusive). Use with start_line to read a specific range.

​
Examples

# Read entire file
read_file(
    description="Check configuration",
    path="/mnt/user-data/workspace/config.yaml"
)

# Read specific line range
read_file(
    description="Read function definition",
    path="/mnt/user-data/workspace/utils.py",
    start_line=10,
    end_line=25
)

# Read log file
read_file(
    description="Check error logs",
    path="/mnt/user-data/workspace/app.log"
)

​
Return Type

Returns a string containing:
  • File contents (full or specified line range)
  • "(empty)" if file is empty
  • Error messages for missing files, permission issues, or invalid paths

​
write_file

Write text content to a file.

​
Parameters

​
description
str
required
Explain why you are writing to this file in short words. ALWAYS PROVIDE THIS PARAMETER FIRST.
​
path
str
required
The absolute path to the file to write to. ALWAYS PROVIDE THIS PARAMETER SECOND.
​
content
str
required
The content to write to the file. ALWAYS PROVIDE THIS PARAMETER THIRD.
​
append
bool
Whether to append to the file instead of overwriting. Default is False.

​
Examples

# Create a new file
write_file(
    description="Create configuration file",
    path="/mnt/user-data/workspace/config.json",
    content='{"api_key": "xxx", "timeout": 30}'
)

# Write analysis results
write_file(
    description="Save analysis results",
    path="/mnt/user-data/outputs/results.txt",
    content="Analysis complete. Found 42 anomalies.\nProcessed 1000 records."
)

# Append to log file
write_file(
    description="Append to log",
    path="/mnt/user-data/workspace/app.log",
    content="[2024-01-15] Process completed successfully\n",
    append=True
)

​
Return Type

Returns:
  • "OK" on success
  • Error message on failure (permission denied, invalid path, etc.)

​
str_replace

Replace a substring in a file with another substring.

​
Parameters

​
description
str
required
Explain why you are replacing the substring in short words. ALWAYS PROVIDE THIS PARAMETER FIRST.
​
path
str
required
The absolute path to the file to replace the substring in. ALWAYS PROVIDE THIS PARAMETER SECOND.
​
old_str
str
required
The substring to replace. ALWAYS PROVIDE THIS PARAMETER THIRD.
​
new_str
str
required
The new substring. ALWAYS PROVIDE THIS PARAMETER FOURTH.
​
replace_all
bool
Whether to replace all occurrences of the substring. If False (default), the substring must appear exactly once in the file.

​
Important Notes

  • If replace_all is False (default), the tool expects the substring to appear exactly once
  • Returns an error if the substring is not found or appears multiple times when replace_all=False

​
Examples

# Replace API endpoint (single occurrence)
str_replace(
    description="Update API endpoint",
    path="/mnt/user-data/workspace/config.py",
    old_str='API_URL = "http://localhost:8000"',
    new_str='API_URL = "https://api.production.com"'
)

# Replace all occurrences
str_replace(
    description="Update variable name",
    path="/mnt/user-data/workspace/script.py",
    old_str="oldVariableName",
    new_str="newVariableName",
    replace_all=True
)

# Update configuration value
str_replace(
    description="Enable debug mode",
    path="/mnt/user-data/workspace/.env",
    old_str="DEBUG=false",
    new_str="DEBUG=true"
)

​
Return Type

Returns:
  • "OK" on success
  • Error message if:
    • String to replace is not found
    • File not found
    • Permission denied
    • Unexpected errors occur

​
Error Handling

All sandbox tools include comprehensive error handling:
  • SandboxError: Caught and returned as formatted error strings
  • FileNotFoundError: Specific error message with path
  • PermissionError: Permission denied errors with context
  • IsADirectoryError: When path is directory but file expected
  • Generic Exception: Unexpected errors with type and message

​
Lazy Initialization

Sandbox tools support lazy initialization:
  • Sandbox is acquired on first tool use
  • Thread directories are created automatically
  • State is persisted across tool calls
  • Thread-safety guaranteed by provider locking

Build docs developers (and LLMs) love

Get started for freeTalk to us