Sandbox Environment

All tool code executes in a secure, isolated sandbox environment. Understanding how the sandbox works helps you write tools that work correctly and securely within the platform's constraints.

What is a Sandbox Environment?

A sandbox is an isolated execution environment that restricts what your code can do. Think of it like a secure room where your tool code runs - it has everything it needs to perform its work, but it can't access or harm anything outside of that room.

The sandbox environment serves several critical purposes:

• Security - Prevents malicious code from accessing your system, other tools, or sensitive data

• Isolation - Ensures that one tool can't interfere with another tool's execution

• Resource control - Limits how much memory, CPU, and time your tool can use

• Consistency - Provides a predictable environment where tools behave the same way every time

• Reliability - Prevents runaway processes or infinite loops from consuming all resources

Every tool execution happens in its own sandbox. When the execution completes (or times out), the sandbox is destroyed, ensuring complete isolation between executions.

Execution limits (current)

• Timeouts — Default 5 seconds, max 30 seconds per execution.

• Code size — Max 100 KB per tool.

• HTTP (fetch) — Max 10 seconds per request, 5 MB response size, allowed methods GET/POST/PUT/PATCH/DELETE, max 5 redirects.

• Blocked — require(), import, eval(), Function(), process, child_process, fs, exec and similar patterns.

Use the Execution > limits API to retrieve the full list of allowed globals and limits from your deployment.

Understanding the Security Model

The sandbox uses a "deny by default" security model - everything is blocked unless explicitly allowed. This means your code can only use APIs and features that have been specifically approved for safe use.

Complete Isolation

The sandbox provides complete isolation from the rest of the system:

• No file system access - Your code cannot read from or write to the file system. This prevents tools from accessing sensitive files, modifying system files, or creating files that could be used maliciously.

• No network access (except via safe fetch API) - Direct network sockets are blocked, but you can use the fetch API to make HTTP/HTTPS requests. This allows tools to call external APIs while preventing low-level network access that could be used maliciously.

• No Node.js modules or require() - You cannot use Node.js's require() function to load modules. This prevents tools from accessing Node.js built-in modules or installing arbitrary packages that could contain security vulnerabilities.

• No process or global object access - Your code cannot access the process object or modify global variables that could affect other tools or the system.

• No setTimeout/setInterval - Timers are blocked to prevent tools from running indefinitely or creating resource-consuming background processes.

Why These Restrictions Matter

These restrictions might seem limiting, but they're essential for security:

• Prevents data breaches - Without file system access, tools can't read sensitive files or configuration

• Prevents system modification - Tools can't modify system files or install malware

• Prevents resource exhaustion - Without timers and unlimited resources, tools can't consume all system resources

• Prevents code injection - Restricted module loading prevents malicious code from being executed

• Ensures isolation - Each tool runs in complete isolation, so one tool can't affect another

These restrictions are automatic and cannot be bypassed. This ensures that even if someone writes malicious code, it cannot harm your system or other tools.

Available APIs and Globals

While many features are restricted, you have access to a comprehensive set of APIs that are sufficient for building powerful tools. These APIs are carefully selected to be both useful and safe.

HTTP Requests

• fetch - A safe HTTP client for making external API calls. This is the primary way to interact with external services. It supports GET, POST, PUT, DELETE, and other HTTP methods, and can include headers, authentication, and request bodies. The fetch API is restricted to HTTP/HTTPS only - it cannot access local network resources or use other protocols.

Logging and Debugging

• console - Full console API for logging and debugging:

• `console.log()` - General logging - `console.error()` - Error messages - `console.warn()` - Warning messages - `console.info()` - Informational messages All console output is captured and available in execution logs, making it easy to debug your tools.

### Data Processing

• JSON - Complete JSON API for parsing and stringifying JSON data. Essential for working with API responses and request bodies.

• Math - Full Math object with all mathematical functions (Math.max, Math.min, Math.round, Math.random, etc.). Useful for calculations and data processing.

• Date - Complete Date API for working with dates and times. You can create dates, format them, calculate differences, and perform all standard date operations.

Type Constructors

• String - String constructor and all string methods (toUpperCase, toLowerCase, split, replace, etc.)

• Number - Number constructor and number-related utilities

• Boolean - Boolean constructor

Data Structures

• Array - Full Array API with all methods (map, filter, reduce, forEach, etc.)

• Object - Object constructor and all object methods (Object.keys, Object.values, Object.assign, etc.)

Asynchronous Operations

• Promise - Full Promise API for handling asynchronous operations. You can create promises, use async/await, and handle asynchronous code naturally.

What This Means in Practice

With these APIs, you can:

• Make HTTP requests to external APIs

• Process and transform data

• Perform calculations

• Work with dates and times

• Handle JSON data

• Debug your code with console logging

• Use modern JavaScript features like async/await

This is sufficient for the vast majority of tool use cases. If you find yourself needing something that's not available, consider whether there's an alternative approach using the available APIs.

Restricted Features and Why They're Blocked

For security reasons, certain features are completely blocked. Understanding why these are restricted helps you understand the security model and work within its constraints.

File System Operations

Blocked: All file system operations (reading files, writing files, listing directories, etc.)

Why: File system access would allow tools to read sensitive configuration files, modify system files, or access data from other tools. This is a major security risk.

Alternative: If you need to work with data, pass it as parameters or fetch it from APIs. If you need to store data, use external services (databases, APIs) rather than the file system.

Network Sockets

Blocked: Direct network socket access (TCP, UDP, WebSockets, etc.)

Why: Low-level network access could be used to connect to internal services, perform port scanning, or establish unauthorized connections.

Alternative: Use the fetch API for HTTP/HTTPS requests. This is sufficient for most use cases and is much safer.

Child Processes

Blocked: Creating child processes or executing system commands

Why: Allowing process execution would let tools run arbitrary system commands, which is an extreme security risk.

Alternative: Perform operations directly in JavaScript rather than calling external programs.

Environment Variables

Blocked: Access to system environment variables (except via config parameter)

Why: Environment variables often contain sensitive information like API keys, database credentials, or system configuration.

Alternative: Use workspace secrets, which are passed via the config parameter. This is more secure and explicit.

Timers

Blocked: setTimeout and setInterval

Why: Timers could be used to create infinite loops or background processes that consume resources indefinitely.

Alternative: Use async/await for asynchronous operations. If you need delays, use Promise-based delays or make your tool return quickly and let the caller handle timing.

Node.js Built-in Modules

Blocked: All Node.js modules (fs, path, crypto, http, etc.)

Why: Many Node.js modules provide access to system resources that should be restricted. Allowing arbitrary module loading would bypass security restrictions.

Alternative: Use the available JavaScript APIs. Most common operations can be performed with standard JavaScript and the provided APIs.

What Happens If You Try to Use Blocked Features?

If your code tries to use a blocked feature, one of two things will happen:

• During validation - If the code is analyzed before execution and blocked features are detected, you'll receive a validation error explaining what's blocked and why.

• During execution - If a blocked feature is used at runtime, the execution will fail with a clear error message indicating what was attempted and why it's not allowed.

These errors are designed to be helpful - they'll tell you exactly what's blocked and suggest alternatives when possible.

Understanding Execution Limits

To ensure fair resource usage and prevent any single tool from consuming all available resources, the sandbox enforces strict execution limits. These limits ensure that the platform remains responsive and available for all users.

Timeout Limits

Maximum execution time: 30 seconds

Each tool execution has a maximum time limit of 30 seconds. If your tool hasn't completed within this time, it will be automatically terminated.

• Why this limit exists: Prevents tools from running indefinitely and consuming resources

• What happens when exceeded: The execution is terminated and returns a timeout error

• How to work within this limit:

• Optimize your code for performance - Use efficient algorithms and data structures - Make API calls asynchronously and in parallel when possible - Break complex operations into smaller, faster steps

For most use cases, 30 seconds is more than sufficient. If you find yourself hitting this limit regularly, consider optimizing your code or breaking the operation into multiple tools.

Memory Limits

Limited memory allocation

Each tool execution has a memory limit to prevent tools from consuming all available memory.

• Why this limit exists: Prevents memory exhaustion that could crash the system or affect other tools

• What happens when exceeded: The execution is terminated with a memory error

• How to work within this limit:

• Avoid loading large datasets into memory all at once - Process data in chunks when possible - Release references to large objects when done with them - Use streaming or pagination for large API responses

### CPU Limits

CPU time limits

Each tool execution has CPU time limits to prevent CPU-intensive operations from blocking other tools.

• Why this limit exists: Ensures fair CPU usage across all tools

• What happens when exceeded: The execution may be throttled or terminated

• How to work within this limit:

• Avoid CPU-intensive operations like complex calculations on large datasets - Use efficient algorithms - Consider breaking CPU-intensive work into smaller chunks

### Best Practices for Working Within Limits

• Keep operations focused - Each tool should do one thing well, not perform multiple complex operations

• Optimize early - Write efficient code from the start rather than optimizing later

• Test with realistic data - Test your tools with data sizes similar to what they'll handle in production

• Monitor execution times - Check execution logs to see how long your tools take and optimize if needed

• Handle errors gracefully - If you hit a limit, return a clear error message rather than crashing

Security Guarantees

The sandbox environment provides several important security guarantees:

• Complete isolation - Your tool cannot access other tools, their data, or system resources

• No persistent state - Each execution starts fresh - there's no way to store data between executions within the sandbox

• Automatic cleanup - When execution completes, the sandbox is destroyed, ensuring no data leaks between executions

• Resource limits - Strict limits prevent resource exhaustion attacks

• Code validation - Code is validated before execution to catch security issues early

These guarantees mean you can safely run tools from any source without worrying about security risks. The sandbox ensures that even malicious code cannot harm your system or other tools.

Working Within the Sandbox

While the sandbox has restrictions, it's designed to support the vast majority of legitimate use cases. Here are some tips for working effectively within the sandbox:

• Use fetch for all network operations - It's safe, powerful, and sufficient for most needs

• Use workspace secrets for configuration - Don't try to access environment variables; use the config parameter instead

• Process data in memory - Since you can't use the file system, work with data in memory using JavaScript data structures

• Return results quickly - Keep execution times reasonable to stay within timeout limits

• Use console.log for debugging - It's your primary tool for understanding what your code is doing

• Handle errors gracefully - If something fails, return a clear error message rather than crashing

The sandbox is designed to be both secure and practical. While it has restrictions, these restrictions enable the platform to safely run code from any source while providing the APIs you need to build powerful tools.