Tool execution modes

Tools in Letta can execute in different environments depending on their type and configuration. Understanding execution modes helps you choose the right approach for your use case.

The four execution modes

Letta supports four distinct ways of executing tools:

Sandbox execution (for custom tools)

• Where: An isolated sandbox environment
• Permissions: Full API access with client injection
• Best for: Dynamic memory management, subagent creation, and multi-agent coordination

Custom tools that you create run in isolated Python environments. Server-side tools automatically receive a client injection with environment variables and a pre-initialized Letta client for full API access, including write operations. Note: Client injection is currently only available for server-side tools when using the Letta API.

Learn more about sandbox execution.

Client-side execution

• Where: Your application (client)
• Permissions: Full control - you manage execution
• Best for: Write operations, sensitive data, local resources, and full API permissions

Tools execute in your own application environment. You receive the tool call request, execute the tool locally, and return the result. This gives you complete control and provides access to local resources.

Learn more about client-side execution.

MCP remote execution

• Where: An external MCP server
• Permissions: Determined by the MCP server
• Best for: External services, shared tools, and server-managed execution

Tools defined by Model Context Protocol (MCP) servers execute on those external servers. Letta forwards the tool call to the MCP server, which handles execution and returns the result.

Learn more about MCP execution.

Built-in privileged execution

• Where: The Letta server (privileged context)
• Permissions: Full system access
• Best for: Web search, code execution, and filesystem operations

Built-in tools like web_search, run_code, and filesystem execute with privileged access on the Letta server. These tools are maintained by Letta and cannot be modified.

Learn more about built-in tools.

Comparison table

Execution mode	Location	Permissions	Modifiable	API access	Use cases
Sandbox	Isolated sandbox	Full	Yes	Full	Memory management, subagent creation
Client-side	Your app	Full	Yes	Full	Sensitive data, local resources
MCP remote	MCP server	Varies	Via server	N/A	External services, APIs
Built-in	Letta server	Privileged	No	Full	System operations

Choosing an execution mode

Use sandbox execution for:

• Dynamic memory management
• Creating or modifying agents programmatically
• Multi-agent coordination and queries
• Creating custom tools with standard logic
• Automatic deployment
• Tools with self-contained logic

Use client-side execution for:

• Sensitive data or credentials
• Enabling access to local resources (such as files, databases, and services)
• Human-in-the-loop approval workflows
• Complete control over tool execution

Use MCP remote execution for:

• Integrating external services (such as GitHub, Slack, and databases)
• Tools that need server-side state management
• Sharing tools across multiple agents
• An external service that provides an MCP server
• When centralized tool management is preferred

Use built-in tools for:

• Web search capabilities
• Sandboxed code execution
• Filesystem access in the agent workspace
• When you trust Letta’s implementation
• Projects that don’t need custom behavior

Execution environment customization

For custom tools in a sandbox execution, you can customize the Python environment.

• Dependencies: Install the Python packages your tools need.
• Environment variables: Set custom environment variables for the API keys and configuration.

See the tool variables guide for more details on environment customization.

Security considerations

Each execution mode has different security implications.

• Sandbox: Tools execute in an isolated environment with full API access.
• Client-side: Security is your responsibility. You need to validate all inputs.
• MCP remote: The MCP server provider manages security.
• Built-in: These trusted Letta implementations come with appropriate sandboxing.

Choose the execution mode that matches your security requirements and trust model.

Related

• Custom tools: Create custom tools.
• Tool types: Understand the tool categories.
• Tool rules: Constrain tool usage.
• Tool variables: Configure environments and dependencies.