Skip to main content

LibreChat is joining ClickHouse. Learn more

LibreChat

Code Interpreter

Let agents write and run code in a sandbox to analyze data, process your files, and produce new ones, or run a code block from any chat yourself.

The Code Interpreter runs code in an isolated sandbox. Agents use it to do math they would otherwise guess at, analyze a spreadsheet you upload, convert files, or produce charts and documents. You can also run a code block from a chat message yourself with Run Code.

The sandbox is a separate service, ClickHouse/code-interpreter (open source, Apache 2.0), which your admin deploys next to LibreChat. It supports Python, Node.js (JavaScript and TypeScript), Go, C and C++, Java, PHP, Rust, and Fortran.

Give an agent code execution

In the Agent Builder, select Add next to Tools, and add Run Code. Save the agent. From then on the agent decides when to run code; you do not need to ask for it explicitly, though "use code to check this" helps when you want an exact answer.

While code runs, the message shows a collapsible row that reads Starting sandbox environment the first time, then Analyzing, and Finished analyzing when it is done. Expand it to see the code the agent wrote and its Output.

Working with files

Attach a file and choose Upload to Code Environment to make it available to the sandbox for that conversation. Files you add under the agent's Run Code settings are available in every chat with that agent. Before each run LibreChat restores the conversation's files into the sandbox; if none of the files the run needs can be restored, the run stops and asks you to attach them again instead of working from stale copies.

Files the code writes come back as rows in the message. Click a row to open it in the Artifacts panel, or download it. HTML, Markdown, plain text, source code, CSV, and Office files (Word, Excel, OpenDocument, PowerPoint decks and templates) get an inline preview. Larger files skip the preview and stay download-only; the default cutoff is 2 MiB of source file. Images the agent reads from the sandbox (PNG, JPEG, GIF, WebP) display inline up to 1 MiB; bigger ones stay in the sandbox where the agent can still process them.

Run a code block yourself

Code blocks in chat messages have a Run Code button next to Copy code when the block's language is one the sandbox can run (Python, JavaScript, TypeScript, Go, C, C++, D, Java, PHP, Rust, or Fortran). Click it and the output appears under the block. This works in any conversation, not only with agents.

Long-running code

If your admin has enabled background tools, the agent's Run Code settings show Background execution, on by default. The agent can start slow code, keep talking to you, and pick up the output and files when the run finishes; by default the result arrives on its own in a follow-up message. Turn the setting off for agents that should always wait for their code.

Memory, CPU time, upload size, and network access are set by whoever runs the sandbox service, not by LibreChat. If code fails with a resource error, ask your admin what the limits are.

Stateful code sessions

By default each run is stateless: don't count on variables or installed packages surviving to the next run. Stateful code sessions, an experimental feature your admin has to turn on, give an agent a workspace that keeps its files under /mnt/data between runs. Each run still starts a fresh process, and the workspace can be reset at any time, so treat it as a scratch area rather than storage.

Turn on Stateful code sessions in the agent's Run Code settings and pick a Stateful environment:

  • User workspace (recommended): one workspace for you, shared by every stateful agent you use.
  • Agent + user workspace: a separate workspace for each agent.
  • Conversation workspace: a fresh workspace for each conversation.

New agents start with the scope set under Settings > Data & Privacy > Code execution > Default stateful workspace; changing that setting doesn't touch existing agents. Files the agent creates or edits in a stateful workspace are listed under a Workspace changes row on its reply, with a download for each.

Running code on your own machine

Admins can also offer code environments: a VM or workstation running the @librechat/code worker, which connects out to LibreChat. When they do, the Agent Builder shows an Execution environment selector, and Machines available in new chats lets an agent offer several machines so each new chat can pick one with Choose another machine.

If you have permission to manage code environments, add your own under Settings > Data & Privacy > Code execution > Code environments: name it, select Connect VM, and run the one-time command it shows on your machine. If your admin enabled browser setup, the setup command can instead open an Approve Machine Setup page, where you confirm the request while signed in.

On an attached machine the agent can browse, read, search, and edit files and run shell commands in the selected workspace. Chat attachments you upload are copied into .librechat/attachments in that workspace before the agent starts. Because these actions change a real machine, the composer shows a Code approval mode for the conversation:

  • Ask before changes: asks before file edits and commands.
  • Accept edits: edits files without asking, still asks before commands.
  • Full access: edits and runs commands without routine prompts. Sandbox limits on the machine still apply.

Which modes you can pick depends on your admin's policy. Pairing a machine authenticates the worker to LibreChat; it doesn't sandbox anything, so isolate the worker as you would any machine that runs untrusted code.

Calling MCP tools from code

With Programmatic Tool Calling, an agent can call selected MCP tools from inside the sandbox: it writes a script that loops over inputs, calls tools, filters the results, and returns only what matters. This saves a round trip through the model for every tool call. The Programmatic toggles stay disabled until the agent has Run Code, and removing Run Code clears them. While the script runs, expand its row to watch a Tool calls trace; the trace is not kept after a page reload. Only tools registered to the agent can be called this way. See Programmatic Tool Calling for how to mark tools.

Setup

Code execution needs an admin to deploy the Code Interpreter service and point LibreChat at it; until then, runs fail. The Run Code button and the agent capability can also be turned off per role. Background execution, stateful sessions, and code environments are each opt-in. See Code Interpreter configuration.

How is this guide?