Code Interpreter API

Introduction

LibreChat's Code Interpreter API provides a secure and hassle-free way to execute code and manage files through a simple API interface. Whether you're using it through LibreChat's Agents or integrating it directly into your applications, the API offers a powerful sandbox environment for running code in multiple programming languages.

Getting Started

1. Deploy the code-interpreter service (Docker Compose or Helm, see the repository's README)
2. Point LibreChat at it with the LIBRECHAT_CODE_BASEURL and LIBRECHAT_CODE_API_KEY environment variables
3. Start executing code and generating files securely through LibreChat's Agents or the "Run Code" button

Key Features

Supported Languages

Execute code in multiple programming languages:

• Python, Node.js (JS/TS), Go, C/C++, Java, PHP, Rust, Fortran, Rscript

Seamless File Handling

• Upload files for processing
• Download generated outputs
• Secure file management
• Session-based file organization

LibreChat restores referenced conversation files into the current Code Interpreter environment before an Agent run. If every required Code Interpreter file fails recovery, the run stops before model invocation and asks the user to reattach the files rather than continuing with stale references.

Security & Convenience

• Secure sandboxed execution environment
• Strong isolation modes (NsJail or microVM via libkrun)
• No local setup required for end users
• Session-based, isolated file storage

Programmatic Tool Calling

Programmatic Tool Calling lets LibreChat Agents route selected MCP tools through the Code Interpreter sandbox. Instead of asking the model to call each tool directly, LibreChat provides a Code Interpreter-backed orchestration tool; generated sandbox code can call registered tool stubs, use loops and conditionals, process intermediate results, and return a final answer.

The sandbox still does not receive general network access. Tool calls are brokered through the Code Interpreter Tool Call Server and LibreChat's registered tool map, so only tools available to the agent can be called.

Background Code Execution

Background execution lets an Agent dispatch long-running code or shell work, continue the conversation, and retrieve the result later through check_background_task. In LibreChat chat, when the work finishes, stdout and generated files appear on the original code call. Generated files are persisted for subsequent turns even if the Agent has not polled the task yet.

This feature is opt-in at the deployment level. Add run_in_background alongside execute_code in the Agents endpoint capabilities, then enable Code Interpreter on the agent. Code execution and shell calls become background-eligible automatically; turn off Background execution in the Code Interpreter tool settings when an agent should opt out. The model still decides per call whether to dispatch eligible work in the background.

Background task state is process-local and does not survive an app restart or move between replicas. Background dispatch also does not extend the Code Interpreter service's execution limit; the deployment's normal server-side timeout still applies.

Stateful Code Sessions

Stateful code sessions let a LibreChat Agent reuse one Code Interpreter sandbox workspace per conversation. Files, installed packages, and working state usually carry over between executions, making iterative analysis and multi-step file generation more efficient.

This feature is opt-in. Enable execute_code and stateful_code_sessions in the Agents endpoint capabilities, enable Code Interpreter on the agent, then turn on Stateful code sessions in its Advanced settings. The workspace may reset at any time. Save important outputs under /mnt/data, and do not otherwise rely on session state as durable storage.

Using the API

In LibreChat

The API has first-class support in LibreChat through these main methods:

1. AI Agents: Enable Code Interpreter in your agent's configuration to allow it to execute code and process files automatically.

2. Manual Execution: Use the "Run Code" button in code blocks within the chat interface, as shown here:

3. Programmatic Tool Calling: Enable the programmatic_tools capability and mark selected MCP tools as Programmatic so agents can orchestrate those tools from sandboxed code.

4. Background Tool Calls: Let an agent dispatch eligible code in the background and continue while it runs.

5. Stateful Code Sessions: Experimentally reuse a per-conversation workspace across an agent's code executions.

Set up API key

• Per-user setup: input your API key in LibreChat when prompted (using the above methods)
• Global setup: use LIBRECHAT_CODE_API_KEY environment variable in the .env file of your project (provides access to all users)

Direct API Integration

The Code Interpreter API can be integrated into any application using a simple API key authentication:

1. Deploy your own code-interpreter instance and create an API key
2. Include the API key in your requests using the x-api-key header

Self-hosted base URL

Set the LIBRECHAT_CODE_BASEURL environment variable to point LibreChat at your self-hosted code-interpreter instance, along with an API key generated on that deployment, used the same way as above.

Core Functionality

Code Execution

• Run code snippets in supported languages
• Receive stdout/stderr output
• Get execution statistics (memory usage, CPU time)
• Handle program arguments
• Access execution status and results

File Operations

• Upload input files
• Download generated outputs
• Preview generated Office files, including PowerPoint .pptx presentations and .potx templates, plus CSV, text, and PDF-like artifacts inline when LibreChat can safely extract/render them
• Display PNG, JPEG, GIF, and WebP images returned by an Agent's read_file tool as viewable artifacts
• List available files
• Delete unnecessary files
• Manage file sessions

Generated artifact previews are intentionally size-bounded. Set FILE_PREVIEW_MAX_EXTRACT_BYTES in LibreChat's .env to change the source-file size limit for inline preview extraction; larger files remain available for download.

Sandbox images returned through read_file have a 1 MiB inline limit. Larger images remain in the sandbox for processing with bash_tool. LIBRECHAT_CODE_IMAGE_CHUNK_BYTES controls only the transport chunk size used while reading eligible images; it does not raise the inline limit.

Limitations

• Code cannot access the network
• Only 10 files can be generated per run
• Resource limits (RAM per execution, file upload size, and request quotas) depend on how you provision and configure your deployment

Use Cases

• Code Testing: Test code snippets in multiple languages
• File Processing: Transform and analyze files programmatically
• AI Applications: Execute AI-generated code securely
• Development Tools: Build interactive coding environments
• Objective Logic: Verify code logic and correctness, improving AI models

Open Source & Self-Hosting

The Code Interpreter service is open source under the Apache 2.0 license at ClickHouse/code-interpreter. Keeping code execution as a separate service keeps the core LibreChat application lightweight: you only deploy the sandbox infrastructure when you need it, and you can scale it independently of the chat app.

The service runs as a set of independently scalable components (an API gateway, sandboxed workers, and a file server) and supports strong isolation modes (NsJail or a microVM via libkrun) so you can run untrusted code safely. See the repository's README for Docker Compose and Helm deployment instructions.

---

Conclusion

The Code Interpreter API provides a secure, convenient way to execute code and manage files in an isolated sandbox. Whether you're using it through LibreChat's Agents or integrating it directly into your applications, it offers a robust solution for code execution needs.

For detailed technical specifications, deployment guides, and the API reference, see the code-interpreter repository.

#LibreChat #CodeExecution #API #Development